Routing | JoyToken | Documentation

Routing decides which model and provider serve a request. New integrations should start with model: "auto", then control the range with tier and API key policy.

Common Requests

Goal	Request
Automatic routing	`model: "auto"`
Select a tier	`model: "auto"` + `tier: “economy"
Pin one model	`model: "GLM-5"`
Force a key to one model	Set fixed model in API key policy
Block models	Set blacklist in API key policy

Tiers

Tier	Use
`economy`	Cost-first, batch, low-risk tasks
`standard`	Balanced default
`premium`	Quality-first or critical production tasks

Wallet Fallback

When the request uses model: "auto" and the current tier lacks balance, JoyToken may try another tier allowed by policy.

Current tier	Fallback order
`premium`	`standard` -> `economy`
`standard`	`premium` -> `economy`
`economy`	`standard` -> `premium`

Pinned model requests do not automatically switch models. If balance or budget is insufficient, the request returns 402 insufficient_quota.

Confirm Routing

Signal	Meaning
`X-DAOE-Used-Model`	Actual selected model
`X-DAOE-Used-Provider`	Provider that served the request
`metadata.model`	Final JoyToken model
`metadata.tier`	Billing and routing tier
`metadata.billing`	Credits and token usage

Troubleshooting

Symptom	Check first
tier not allowed	API key policy allows the tier
model not allowed	fixed model or blacklist
IP not allowed	server egress IP is allowlisted
`auto` fails	policy, tier, and balance still leave candidate models
pinned model fails	model availability, wallet, and budget