Skip to navigation
Agora Public 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.

Fiat routes need the bank account on file first. Add the bank account you’ll send from (mint from usd) or receive into (redeem to usd) before you transact. If a wire arrives from — or a payout is owed to — a bank account Agora hasn’t added and verified, settlement is held and processing is delayed until it’s on file.

Supported topologies

from.currencyto.currency (+ to.chain)directionBehavior
usdausd on a chainmint-fiatMint: wire USD with the memo, receive AUSD at the destination
usdcausd on a chainmint-stablecoinMint from stablecoin: send USDC to the mint address, receive AUSD at the destination
ausdusd (bank account)redeem-fiatRedeem: send AUSD to the redeem address, receive a USD payout
ausdusdc on a chainredeem-stablecoinRedeem to tokens: send AUSD to the redeem address, receive USDC

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