Overview

An account is a place value enters or leaves: a fiat bank account or a blockchain wallet your organization owns. Routes reference an account as their destination via to.accountId, so accounts are the foundation routes build on.

GET /v0/accounts returns both kinds in one paginated list, distinguished by a kind discriminator:

• kind: "bank": a verified USD bank account. Carries bankName, the full accountNumber, routingNumber (ABA or SWIFT/BIC), the beneficiary (account-holder name on the wire), and currency (usd today).
• kind: "wallet": a customer-owned blockchain address. Carries the address (EIP-55 checksummed for EVM, base58 for Solana), an addressFormat of ethereum (covers every EVM chain) or solana, and a networks array of per-network entitlements (below).

Wallet entitlements

Each wallet networks entry pairs a chain with its entitlements: one per capability the wallet holds on that network. Each entitlement has a type and a status.

• type: mint (the mint capability, which currently also covers redeem), instant_settlement (the instant-settlement whitelist), or rewards (rewards eligibility).
• status: the entitlement’s lifecycle state. The API never auto-approves.
  • approved: active.
  • conditionally_approved: usable now while final approval completes (details below). Applies primarily to mint.
  • pending_approval: requested and under Agora review.
  • pending_removal: removal requested and under review.
  • removed: no longer active.
  • rejected: reviewed and not approved.

Registering a wallet starts a mint entitlement on each network, plus an instant_settlement entitlement on networks that support it. rewards is granted by Agora and cannot be requested through the API.

Conditionally approved entitlements

conditionally_approved lets you use an entitlement before its approval is final. Today it applies primarily to the mint entitlement, which currently covers both minting and redeeming.

When you register a wallet, an initial scan runs immediately. If it passes, the mint entitlement becomes conditionally_approved and you can start using it. For mint, that means you can create routes with the wallet and initiate transfers from it to kick off a mint or redeem.

We allow this because a secondary scan takes longer to finish. Once the initial scan is clean, the secondary scan almost never fails. If it clears, your mint or redeem completes normally and the entitlement becomes approved. If it does not clear, the entitlement becomes rejected and any funds you sent for a mint or redeem are returned.

Managing accounts

• POST /v0/accounts: register a wallet (with the networks to register it on) or a bank account. Bank accountNumber and routingNumber accept uppercase letters and digits, 6 to 100 characters.
• PUT /v0/accounts/{accountId}: rename an account (setName), register an existing wallet on another network (addNetwork), or request an entitlement (requestEntitlement, currently instant_settlement) on a network.

Reference an account’s id as a route’s to.accountId: a wallet account receives ausd (or another stablecoin) on a specific chain, while a bank account receives a usd payout. Authentication is required, see the Authentication guide; the endpoints below return the full response shapes and support cursor pagination.