Skip to navigation
Agora Sandbox APIEndpointsRoutes

Create a Route

Create a persistent source → destination route. The response includes reusable settlement instructions — a wire memo for fiat sources, or one mint or redeem address per supported chain for blockchain sources — that the caller uses to initiate transfers. A single set of instructions is valid indefinitely; every inbound transfer matching them triggers a separate settlement to the route’s destination.

from.currency, to.currency, and the destination to.chain determine the route’s topology, returned as direction. to.accountId references a registered account from GET /v0/accounts.

No US dollars move in the sandbox. Fiat routes return fake wire instructions so you can build fiat flows. Never send a real wire to them. To test a mint, simulate the wire with POST /v0/sandbox/wires.

Supported topologies

from.currencyto.currency (+ to.chain)directionBehavior
usdausd on a chainmint-fiatMint from simulated USD. Never send a real wire.
ctkausd on a chainmint-stablecoinMint from stablecoin: send CTK to the mint address, receive AUSD at the destination
ausdusd (bank account)redeem-fiatRedeem to simulated USD. No payout is sent.
ausdctk on a chainredeem-stablecoinRedeem to tokens: send AUSD to the redeem address, receive CTK

200, 201, or 409

Route ids are deterministic from their canonical inputs (organization, destination account, chain, currency), so calling this endpoint again with the same inputs is safe:

  • 201 — no route existed for these inputs; one was created.
  • 200 — a route for these inputs already existed. Nothing was written; the response is that existing route, in the same shape a 201 would have returned.
  • 409 route_already_exists — the deterministic id is occupied by a route this call couldn’t read back cleanly. This is an internal inconsistency, not an ordinary duplicate create; context.routeId names the id. Contact support rather than retrying.

Authentication

AuthorizationBearer

Session JWT from POST /v0/auth/token, sent as Authorization: Bearer <sessionJwt>.

See Authentication for more details.

Request

This endpoint expects an object.
fromobjectRequired
toobjectRequired
namestringOptional<=200 characters

Response

The route already existed, so nothing was created and the stored route is returned.
idstringformat: "uuid"

Deterministic route UUID; same canonical inputs always derive the same id.

createdAtdatetime
directionenum
Which of the four flows this route is.
Allowed values:
toobject
instructionslist of objects

Next-step instructions. Mint-fiat: one wire instruction with memo + beneficiary. On-chain directions: one deposit address per supported chain, alphabetical by chain.

namestring or nullOptional

User-set label, or null when unset.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error