{ "info": { "title": "Agora Public API (Sandbox)", "description": "Sandbox environment. Testnets only, and no real funds: addresses here cannot receive money. Build against this, then move to the production spec.\n\nPublic API for Agora's stablecoin platform. Authenticate with an API key to manage the accounts and routes that move funds into and out of AUSD, and read real-time AUSD supply metrics across all supported chains.\n\n## Financial Precision\nAll supply values are strings (not JSON numbers) to avoid floating-point precision issues. This follows industry standard practice (Circle, Stripe).\n\n## Partial Responses\nWhen one or more chains are temporarily unavailable, the `/v0/metrics` endpoint returns `partial: true` and omits aggregate totals rather than publishing a silently-truncated figure.", "version": "0.1.0", "contact": { "name": "Agora Engineering", "url": "https://agora.finance" } }, "servers": [ { "url": "https://api.sandbox.agora.finance", "description": "Sandbox" } ], "openapi": "3.1.1", "paths": { "/v0/accounts": { "post": { "operationId": "accounts.create", "summary": "Register a wallet or bank account", "tags": [ "accounts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: register a customer-owned blockchain address.", "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "On-chain address to register. EVM hex is normalized to lowercase; Solana base58 is kept verbatim." }, "name": { "type": "string", "maxLength": 200, "description": "User-set label. Free-form; max 200 characters." }, "networks": { "type": "array", "items": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Blockchain network identifier. Use this to filter or group supply data by chain. Values are stable; new networks may be added but existing ones will not be renamed." }, "minItems": 1, "description": "Networks to register this address on. Each must be compatible with the address format." } }, "required": [ "kind", "address", "networks" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: register a customer-owned bank account.", "enum": [ "bank" ], "type": "string" }, "accountNumber": { "type": "string", "pattern": "^[A-Z0-9\\s]+$", "description": "Bank account number. 6-100 uppercase letters and digits; embedded spaces are ignored." }, "bankName": { "type": "string", "description": "Name of the receiving bank." }, "beneficiary": { "type": "string", "description": "Account-holder name on the wire. Part of the account's identity (with routing + account number): omnibus/custodian accounts share one account number across beneficiaries, so this disambiguates them." }, "name": { "type": "string", "maxLength": 200, "description": "User-set label. Free-form; max 200 characters." }, "routingNumber": { "type": "string", "pattern": "^[A-Z0-9\\s]+$", "description": "ABA routing number (US) or SWIFT/BIC (international). 6-100 uppercase letters and digits; embedded spaces are ignored." } }, "required": [ "kind", "accountNumber", "bankName", "beneficiary", "routingNumber" ] } ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "address": { "type": "string", "description": "On-chain address. EIP-55 checksummed for EVM (`ethereum`), base58 for Solana." }, "addressFormat": { "enum": [ "ethereum" ], "type": "string", "description": "Address syntax family. `ethereum` covers every EVM chain (Ethereum, Base, Polygon, Arbitrum, etc.); per-chain authorization is enforced separately via the account's chain entitlements." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this address was added to the org." }, "kind": { "description": "Discriminator: this is a customer-owned blockchain address.", "enum": [ "wallet" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "networks": { "type": "array", "items": { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Network the wallet is registered on (kebab-case public network id)." }, "entitlements": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "instant_settlement", "mint", "rewards" ], "type": "string", "description": "Entitlement type. `mint` is the mint capability gated by the per-chain compliance scan; `instant_settlement` is the instant-settlement whitelist; `rewards` is rewards eligibility." }, "status": { "enum": [ "approved", "conditionally_approved", "pending_approval", "pending_removal", "rejected", "removed" ], "type": "string", "description": "Entitlement status. `pending_approval` is requested and under Agora review; `approved` is active. `conditionally_approved` applies to `mint` only: the address is usable now (screening and whitelisting are auto-initiated) while final approval is still pending internally. `instant_settlement` and `rewards` stay `pending_approval` until reviewed. The API never auto-approves." } }, "required": [ "type", "status" ] }, "description": "Entitlement states on this network, one per type the wallet holds on the chain." } }, "required": [ "chain", "entitlements" ], "description": "Per-network entitlement state for the wallet." }, "description": "The networks this address is registered on, each with its per-type entitlement states." } }, "required": [ "id", "address", "addressFormat", "createdAt", "kind", "name", "networks" ], "description": "Customer-owned blockchain address (CustomerAddress)." }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "accountNumber": { "type": "string", "minLength": 1, "description": "Full bank account number." }, "bankName": { "type": "string", "description": "Name of the receiving bank." }, "beneficiary": { "type": "string", "description": "Account-holder name on the wire. Part of the account's identity: distinguishes accounts that share a routing + account number (e.g. omnibus/custodian accounts holding several funds under one account number)." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this account was added to the org." }, "currency": { "enum": [ "usd" ], "type": "string", "description": "Settlement currency. Today only `usd`; will extend as new currencies launch." }, "kind": { "description": "Discriminator: this is a customer-owned bank account.", "enum": [ "bank" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "routingNumber": { "type": "string", "description": "ABA routing number identifying the receiving bank. A public bank identifier, returned in full." } }, "required": [ "id", "accountNumber", "bankName", "beneficiary", "createdAt", "currency", "kind", "name", "routingNumber" ], "description": "Customer-owned bank account (WireDetail)." } ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "409": { "description": "An account with these details already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_409_account_already_exists" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] }, "get": { "operationId": "accounts.get", "summary": "List the caller's wallet and bank accounts", "tags": [ "accounts" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor. Pass the `nextCursor` from the previous response; omit to fetch the first page." }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque pagination cursor. Pass the `nextCursor` from the previous response; omit to fetch the first page." }, { "name": "limit", "in": "query", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200, "description": "Page size. Defaults to 50; capped at 200." }, "allowEmptyValue": true, "allowReserved": true, "description": "Page size. Defaults to 50; capped at 200." }, { "name": "createdAt.gt", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Exclusive lower bound on when the account was added, as an ISO-8601 timestamp." }, "allowEmptyValue": true, "allowReserved": true, "description": "Exclusive lower bound on when the account was added, as an ISO-8601 timestamp." }, { "name": "createdAt.gte", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on when the account was added, as an ISO-8601 timestamp." }, "allowEmptyValue": true, "allowReserved": true, "description": "Inclusive lower bound on when the account was added, as an ISO-8601 timestamp." }, { "name": "createdAt.lt", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Exclusive upper bound on when the account was added, as an ISO-8601 timestamp. Pairs with `createdAt.gte` to select a period without depending on its last instant." }, "allowEmptyValue": true, "allowReserved": true, "description": "Exclusive upper bound on when the account was added, as an ISO-8601 timestamp. Pairs with `createdAt.gte` to select a period without depending on its last instant." }, { "name": "createdAt.lte", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound on when the account was added, as an ISO-8601 timestamp." }, "allowEmptyValue": true, "allowReserved": true, "description": "Inclusive upper bound on when the account was added, as an ISO-8601 timestamp." }, { "name": "kind", "in": "query", "schema": { "enum": [ "bank", "wallet" ], "type": "string", "description": "Return only accounts of this kind." }, "allowEmptyValue": true, "allowReserved": true, "description": "Return only accounts of this kind." }, { "name": "network", "in": "query", "schema": { "type": "array", "items": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string" }, "minItems": 1, "description": "Return only wallets registered on any of these networks, comma-separated. Registration is independent of entitlement state, so a wallet whose entitlement on a network was rejected or removed still matches; read `networks[].entitlements` for the current state. Bank accounts carry no network and are never matched by this filter." }, "style": "form", "explode": false, "allowEmptyValue": true, "allowReserved": true, "description": "Return only wallets registered on any of these networks, comma-separated. Registration is independent of entitlement state, so a wallet whose entitlement on a network was rejected or removed still matches; read `networks[].entitlements` for the current state. Bank accounts carry no network and are never matched by this filter." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "address": { "type": "string", "description": "On-chain address. EIP-55 checksummed for EVM (`ethereum`), base58 for Solana." }, "addressFormat": { "enum": [ "ethereum" ], "type": "string", "description": "Address syntax family. `ethereum` covers every EVM chain (Ethereum, Base, Polygon, Arbitrum, etc.); per-chain authorization is enforced separately via the account's chain entitlements." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this address was added to the org." }, "kind": { "description": "Discriminator: this is a customer-owned blockchain address.", "enum": [ "wallet" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "networks": { "type": "array", "items": { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Network the wallet is registered on (kebab-case public network id)." }, "entitlements": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "instant_settlement", "mint", "rewards" ], "type": "string", "description": "Entitlement type. `mint` is the mint capability gated by the per-chain compliance scan; `instant_settlement` is the instant-settlement whitelist; `rewards` is rewards eligibility." }, "status": { "enum": [ "approved", "conditionally_approved", "pending_approval", "pending_removal", "rejected", "removed" ], "type": "string", "description": "Entitlement status. `pending_approval` is requested and under Agora review; `approved` is active. `conditionally_approved` applies to `mint` only: the address is usable now (screening and whitelisting are auto-initiated) while final approval is still pending internally. `instant_settlement` and `rewards` stay `pending_approval` until reviewed. The API never auto-approves." } }, "required": [ "type", "status" ] }, "description": "Entitlement states on this network, one per type the wallet holds on the chain." } }, "required": [ "chain", "entitlements" ], "description": "Per-network entitlement state for the wallet." }, "description": "The networks this address is registered on, each with its per-type entitlement states." } }, "required": [ "id", "address", "addressFormat", "createdAt", "kind", "name", "networks" ], "description": "Customer-owned blockchain address (CustomerAddress)." }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "accountNumber": { "type": "string", "minLength": 1, "description": "Full bank account number." }, "bankName": { "type": "string", "description": "Name of the receiving bank." }, "beneficiary": { "type": "string", "description": "Account-holder name on the wire. Part of the account's identity: distinguishes accounts that share a routing + account number (e.g. omnibus/custodian accounts holding several funds under one account number)." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this account was added to the org." }, "currency": { "enum": [ "usd" ], "type": "string", "description": "Settlement currency. Today only `usd`; will extend as new currencies launch." }, "kind": { "description": "Discriminator: this is a customer-owned bank account.", "enum": [ "bank" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "routingNumber": { "type": "string", "description": "ABA routing number identifying the receiving bank. A public bank identifier, returned in full." } }, "required": [ "id", "accountNumber", "bankName", "beneficiary", "createdAt", "currency", "kind", "name", "routingNumber" ], "description": "Customer-owned bank account (WireDetail)." } ] }, "description": "Page of accounts, newest first, tie-broken by id." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Pass back verbatim as the `cursor` query param to fetch the next page; null when no more results." } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/accounts/{accountId}": { "get": { "operationId": "accounts.getById", "summary": "Get a single account by id", "tags": [ "accounts" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Id of the account to fetch; must belong to the caller's org." }, "description": "Id of the account to fetch; must belong to the caller's org." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "address": { "type": "string", "description": "On-chain address. EIP-55 checksummed for EVM (`ethereum`), base58 for Solana." }, "addressFormat": { "enum": [ "ethereum" ], "type": "string", "description": "Address syntax family. `ethereum` covers every EVM chain (Ethereum, Base, Polygon, Arbitrum, etc.); per-chain authorization is enforced separately via the account's chain entitlements." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this address was added to the org." }, "kind": { "description": "Discriminator: this is a customer-owned blockchain address.", "enum": [ "wallet" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "networks": { "type": "array", "items": { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Network the wallet is registered on (kebab-case public network id)." }, "entitlements": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "instant_settlement", "mint", "rewards" ], "type": "string", "description": "Entitlement type. `mint` is the mint capability gated by the per-chain compliance scan; `instant_settlement` is the instant-settlement whitelist; `rewards` is rewards eligibility." }, "status": { "enum": [ "approved", "conditionally_approved", "pending_approval", "pending_removal", "rejected", "removed" ], "type": "string", "description": "Entitlement status. `pending_approval` is requested and under Agora review; `approved` is active. `conditionally_approved` applies to `mint` only: the address is usable now (screening and whitelisting are auto-initiated) while final approval is still pending internally. `instant_settlement` and `rewards` stay `pending_approval` until reviewed. The API never auto-approves." } }, "required": [ "type", "status" ] }, "description": "Entitlement states on this network, one per type the wallet holds on the chain." } }, "required": [ "chain", "entitlements" ], "description": "Per-network entitlement state for the wallet." }, "description": "The networks this address is registered on, each with its per-type entitlement states." } }, "required": [ "id", "address", "addressFormat", "createdAt", "kind", "name", "networks" ], "description": "Customer-owned blockchain address (CustomerAddress)." }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "accountNumber": { "type": "string", "minLength": 1, "description": "Full bank account number." }, "bankName": { "type": "string", "description": "Name of the receiving bank." }, "beneficiary": { "type": "string", "description": "Account-holder name on the wire. Part of the account's identity: distinguishes accounts that share a routing + account number (e.g. omnibus/custodian accounts holding several funds under one account number)." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this account was added to the org." }, "currency": { "enum": [ "usd" ], "type": "string", "description": "Settlement currency. Today only `usd`; will extend as new currencies launch." }, "kind": { "description": "Discriminator: this is a customer-owned bank account.", "enum": [ "bank" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "routingNumber": { "type": "string", "description": "ABA routing number identifying the receiving bank. A public bank identifier, returned in full." } }, "required": [ "id", "accountNumber", "bankName", "beneficiary", "createdAt", "currency", "kind", "name", "routingNumber" ], "description": "Customer-owned bank account (WireDetail)." } ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `account_not_found`: Account not found.\n- `not_found`: Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_account_not_found_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] }, "put": { "operationId": "accounts.update", "summary": "Update an account nickname, add a network, or request an entitlement", "tags": [ "accounts" ], "parameters": [ { "name": "accountId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Id of the account to update; must belong to the caller's org." }, "description": "Id of the account to update; must belong to the caller's org." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "enum": [ "setName", "addNetwork", "requestEntitlement" ], "type": "string" }, "name": { "type": "string", "maxLength": 200, "description": "User-set label. Free-form; max 200 characters." }, "network": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string" }, "entitlement": { "description": "Entitlement to request. Moves to pending_approval; granting stays Agora-side.", "enum": [ "instant_settlement" ], "type": "string" } }, "required": [ "operation" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "address": { "type": "string", "description": "On-chain address. EIP-55 checksummed for EVM (`ethereum`), base58 for Solana." }, "addressFormat": { "enum": [ "ethereum" ], "type": "string", "description": "Address syntax family. `ethereum` covers every EVM chain (Ethereum, Base, Polygon, Arbitrum, etc.); per-chain authorization is enforced separately via the account's chain entitlements." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this address was added to the org." }, "kind": { "description": "Discriminator: this is a customer-owned blockchain address.", "enum": [ "wallet" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "networks": { "type": "array", "items": { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Network the wallet is registered on (kebab-case public network id)." }, "entitlements": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "instant_settlement", "mint", "rewards" ], "type": "string", "description": "Entitlement type. `mint` is the mint capability gated by the per-chain compliance scan; `instant_settlement` is the instant-settlement whitelist; `rewards` is rewards eligibility." }, "status": { "enum": [ "approved", "conditionally_approved", "pending_approval", "pending_removal", "rejected", "removed" ], "type": "string", "description": "Entitlement status. `pending_approval` is requested and under Agora review; `approved` is active. `conditionally_approved` applies to `mint` only: the address is usable now (screening and whitelisting are auto-initiated) while final approval is still pending internally. `instant_settlement` and `rewards` stay `pending_approval` until reviewed. The API never auto-approves." } }, "required": [ "type", "status" ] }, "description": "Entitlement states on this network, one per type the wallet holds on the chain." } }, "required": [ "chain", "entitlements" ], "description": "Per-network entitlement state for the wallet." }, "description": "The networks this address is registered on, each with its per-type entitlement states." } }, "required": [ "id", "address", "addressFormat", "createdAt", "kind", "name", "networks" ], "description": "Customer-owned blockchain address (CustomerAddress)." }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this account; safe to cache or display." }, "accountNumber": { "type": "string", "minLength": 1, "description": "Full bank account number." }, "bankName": { "type": "string", "description": "Name of the receiving bank." }, "beneficiary": { "type": "string", "description": "Account-holder name on the wire. Part of the account's identity: distinguishes accounts that share a routing + account number (e.g. omnibus/custodian accounts holding several funds under one account number)." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 UTC timestamp when this account was added to the org." }, "currency": { "enum": [ "usd" ], "type": "string", "description": "Settlement currency. Today only `usd`; will extend as new currencies launch." }, "kind": { "description": "Discriminator: this is a customer-owned bank account.", "enum": [ "bank" ], "type": "string" }, "name": { "type": "string", "description": "User-set label. Free-form; may be empty if the user hasn't set one." }, "routingNumber": { "type": "string", "description": "ABA routing number identifying the receiving bank. A public bank identifier, returned in full." } }, "required": [ "id", "accountNumber", "bankName", "beneficiary", "createdAt", "currency", "kind", "name", "routingNumber" ], "description": "Customer-owned bank account (WireDetail)." } ] } } } }, "400": { "description": "- `entitlement_not_requestable`: This entitlement cannot be requested in its current state.\n- `parameter_invalid`: One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_entitlement_not_requestable_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `account_not_found`: Account not found.\n- `not_found`: Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_account_not_found_not_found" } } } }, "409": { "description": "An account with these details already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_409_account_already_exists" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/auth/token": { "post": { "operationId": "auth.token", "summary": "Exchange an access key for a session JWT", "tags": [ "auth" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionJwt": { "type": "string", "description": "Short-lived session JWT. Send it as `Authorization: Bearer ` on every authenticated endpoint." } }, "required": [ "sessionJwt" ] } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } }, "503": { "description": "An upstream service is temporarily unavailable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_503_service_unavailable" } } } } }, "security": [ { "accessKey": [] } ] } }, "/v0/metrics/circulating-supply": { "get": { "operationId": "metrics.circulatingSupply", "summary": "Circulating AUSD supply across all chains", "tags": [ "metrics" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string", "description": "Aggregate circulating AUSD supply as a plain-text (`text/plain`) decimal number. The response body is the raw decimal (e.g. `987654321.654321`), not a JSON value." } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } } } }, "/v0/metrics": { "get": { "operationId": "metrics.get", "summary": "Aggregate and per-chain AUSD supply metrics", "tags": [ "metrics" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "chains": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "string", "description": "CAIP-2 chain identifier (e.g. 'eip155:1' for Ethereum, 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp' for Solana). Use this for cross-referencing with DeFi Llama, CoinGecko, or on-chain data." }, "circulatingSupply": { "type": "string", "description": "AUSD in public circulation on this chain (total minus premint reserves), as a decimal string (e.g. `400000000.000000`). Use this for market cap calculations and exchange integrations." }, "network": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Blockchain network identifier. Use this to filter or group supply data by chain. Values are stable; new networks may be added but existing ones will not be renamed." }, "totalSupply": { "type": "string", "description": "Total AUSD minted on this chain, as a decimal string in human-readable units (not raw on-chain units, e.g. `500000000.000000`, not `500000000000000`). Use this when you need the gross supply figure for a single chain." } }, "required": [ "chainId", "circulatingSupply", "network", "totalSupply" ] }, "description": "Per-chain supply breakdown. Only chains with a currently cached successful result are included; chains that have never succeeded (or are in a persistent outage on this pod) are omitted and cause `partial` to be true." }, "circulatingSupply": { "type": "string", "description": "Aggregate circulating AUSD supply across all chains, as a decimal string (e.g. `987654321.654321`). This is the sum of all per-chain circulatingSupply values. Omitted when `partial` is true." }, "partial": { "type": "boolean", "description": "True when one or more chains are missing from the response (cold start before a chain's first successful fetch, or a persistent chain outage). When true, aggregate `totalSupply` and `circulatingSupply` are **omitted**, since publishing a total that silently excludes chains would look like a large supply drop to market-data consumers." }, "totalSupply": { "type": "string", "description": "Aggregate total AUSD supply across all chains, as a decimal string (e.g. `1234567890.123456`). This is the sum of all per-chain totalSupply values. Omitted when `partial` is true." } }, "required": [ "chains", "partial" ] } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } } } }, "/v0/metrics/total-supply": { "get": { "operationId": "metrics.totalSupply", "summary": "Total AUSD supply across all chains", "tags": [ "metrics" ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string", "description": "Aggregate total AUSD supply as a plain-text (`text/plain`) decimal number. The response body is the raw decimal (e.g. `1234567890.123456`), not a JSON value." } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } } } }, "/v0/quotes": { "post": { "operationId": "quotes.create", "summary": "Quote a same-chain conversion between AUSD and USDC or USDT", "tags": [ "quotes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sender": { "type": "object", "properties": { "kind": { "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "EOA or smart account that submits every execution step. It is the `from` on each step's transaction." }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "currency": { "enum": [ "ausd", "ctk" ], "type": "string", "description": "Token being sent or received." } }, "required": [ "kind", "address", "chain", "currency" ] }, "receiver": { "type": "object", "properties": { "kind": { "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "EOA or smart account that receives the output." }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "currency": { "enum": [ "ausd", "ctk" ], "type": "string", "description": "Token being sent or received." } }, "required": [ "kind", "address", "chain", "currency" ] }, "senderAmount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Fixes the input side. Provide exactly one of `senderAmount` or `receiverAmount`; the other is computed on the quote." }, "receiverAmount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Fixes the output side. Provide exactly one of `senderAmount` or `receiverAmount`; the other is computed on the quote." }, "slippageBps": { "type": "integer", "minimum": 0, "description": "Basis points of allowed slippage from the quoted rate. Default and cap are set per chain; values above the cap are clamped rather than rejected. The effective value is echoed on the quote." } }, "required": [ "sender", "receiver" ], "description": "One side must be `ausd` and the other must not. Both sides must be on the same chain. Currencies offered per chain: avalanche-fuji (ausd, ctk), ethereum-sepolia (ausd, ctk)." } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "enum": [ "relay" ], "type": "string", "description": "Which provider executes this quote. `relay` is the only value today; further providers join as their integrations land." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Deposit must land onchain by this time." }, "sender": { "type": "object", "properties": { "kind": { "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "EOA or smart account that submits every execution step. It is the `from` on each step's transaction." }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "currency": { "enum": [ "ausd", "ctk" ], "type": "string", "description": "Token being sent or received." } }, "required": [ "kind", "address", "chain", "currency" ] }, "receiver": { "type": "object", "properties": { "kind": { "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "EOA or smart account that receives the output." }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "currency": { "enum": [ "ausd", "ctk" ], "type": "string", "description": "Token being sent or received." } }, "required": [ "kind", "address", "chain", "currency" ] }, "senderAmount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount in decimal token units, ex. `10.00`." }, "receiverAmount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount in decimal token units, ex. `10.00`." }, "slippageBps": { "type": "integer", "minimum": 0, "description": "Effective value after the chain's default and cap." }, "fees": { "type": "object", "properties": { "gasUsd": { "type": "string", "description": "USD cost of the steps the sender's own wallet executes directly (ex. the `erc20Approve` step), distinct from the relayer's own gas cost in `relayerGasUsd`. Ex. `0.035869`." }, "relayerUsd": { "type": "string", "description": "The relayer's total fee: `relayerGasUsd` plus `relayerServiceUsd`. Ex. `0.056939`." }, "relayerGasUsd": { "type": "string", "description": "Portion of `relayerUsd` covering the relayer's own on-chain execution cost. Ex. `0.035141`." }, "relayerServiceUsd": { "type": "string", "description": "Portion of `relayerUsd` covering the relayer's service margin. Ex. `0.021798`." }, "appUsd": { "type": "string", "description": "Agora's own fee on this quote, separate from the relayer's." } }, "required": [ "gasUsd", "relayerUsd", "relayerGasUsd", "relayerServiceUsd", "appUsd" ], "description": "Cost breakdown in USD. Informational: nothing here is deducted from `senderAmount` or `receiverAmount`, which already reflect the quoted rate." }, "executionSteps": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "action": { "enum": [ "erc20Approve" ], "type": "string" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "details": { "type": "object", "properties": { "token": { "type": "string" }, "spender": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount in decimal token units, ex. `10.00`." } }, "required": [ "token", "spender", "amount" ] }, "transaction": { "type": "object", "properties": { "from": { "type": "string", "description": "The sender's address." }, "to": { "type": "string", "description": "Contract to call." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "description": "Native value in base units." } }, "required": [ "from", "to", "data", "value" ] } }, "required": [ "action", "chain", "details", "transaction" ], "title": "ERC-20 Approve" }, { "type": "object", "properties": { "action": { "enum": [ "relayDepositErc20" ], "type": "string" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "transaction": { "type": "object", "properties": { "from": { "type": "string", "description": "The sender's address." }, "to": { "type": "string", "description": "Contract to call." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "description": "Native value in base units." } }, "required": [ "from", "to", "data", "value" ] } }, "required": [ "action", "chain", "transaction" ], "title": "Relay Deposit" }, { "type": "object", "properties": { "action": { "enum": [ "relayTransferAndMulticall" ], "type": "string" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "transaction": { "type": "object", "properties": { "from": { "type": "string", "description": "The sender's address." }, "to": { "type": "string", "description": "Contract to call." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "description": "Native value in base units." } }, "required": [ "from", "to", "data", "value" ] } }, "required": [ "action", "chain", "transaction" ], "title": "Relay Transfer + Multicall" } ] }, "minItems": 1, "description": "Ordered steps the caller executes in turn to fulfill the quote. `erc20Approve` appears only when the sender's existing allowance is insufficient. New `action` values may be added; tolerate unknown ones." }, "transactionId": { "type": "string", "format": "uuid", "description": "Poll GET /v0/transactions/{txnId} with this. 404 until the deposit is observed." } }, "required": [ "id", "provider", "createdAt", "expiresAt", "sender", "receiver", "senderAmount", "receiverAmount", "slippageBps", "fees", "executionSteps", "transactionId" ] }, "description": "One element per provider that returned a route. Never empty on success." } }, "required": [ "quotes" ] } } } }, "400": { "description": "- `chain_unsupported`: The requested chain is not supported.\n- `currency_unsupported`: The requested currency is not supported.\n- `parameter_invalid`: One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_chain_unsupported_currency_unsupported_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.\n- `wallet_blocked`: Wallet blocked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden_wallet_blocked" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } }, "503": { "description": "An upstream service is temporarily unavailable. Please retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_503_service_unavailable" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/quotes/{quoteId}": { "get": { "operationId": "quotes.getById", "summary": "Re-read a quote's steps and fees as they were returned at creation", "tags": [ "quotes" ], "parameters": [ { "name": "quoteId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "enum": [ "relay" ], "type": "string", "description": "Which provider executes this quote. `relay` is the only value today; further providers join as their integrations land." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Deposit must land onchain by this time." }, "sender": { "type": "object", "properties": { "kind": { "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "EOA or smart account that submits every execution step. It is the `from` on each step's transaction." }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "currency": { "enum": [ "ausd", "ctk" ], "type": "string", "description": "Token being sent or received." } }, "required": [ "kind", "address", "chain", "currency" ] }, "receiver": { "type": "object", "properties": { "kind": { "enum": [ "wallet" ], "type": "string" }, "address": { "type": "string", "description": "EOA or smart account that receives the output." }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "currency": { "enum": [ "ausd", "ctk" ], "type": "string", "description": "Token being sent or received." } }, "required": [ "kind", "address", "chain", "currency" ] }, "senderAmount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount in decimal token units, ex. `10.00`." }, "receiverAmount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount in decimal token units, ex. `10.00`." }, "slippageBps": { "type": "integer", "minimum": 0, "description": "Effective value after the chain's default and cap." }, "fees": { "type": "object", "properties": { "gasUsd": { "type": "string", "description": "USD cost of the steps the sender's own wallet executes directly (ex. the `erc20Approve` step), distinct from the relayer's own gas cost in `relayerGasUsd`. Ex. `0.035869`." }, "relayerUsd": { "type": "string", "description": "The relayer's total fee: `relayerGasUsd` plus `relayerServiceUsd`. Ex. `0.056939`." }, "relayerGasUsd": { "type": "string", "description": "Portion of `relayerUsd` covering the relayer's own on-chain execution cost. Ex. `0.035141`." }, "relayerServiceUsd": { "type": "string", "description": "Portion of `relayerUsd` covering the relayer's service margin. Ex. `0.021798`." }, "appUsd": { "type": "string", "description": "Agora's own fee on this quote, separate from the relayer's." } }, "required": [ "gasUsd", "relayerUsd", "relayerGasUsd", "relayerServiceUsd", "appUsd" ], "description": "Cost breakdown in USD. Informational: nothing here is deducted from `senderAmount` or `receiverAmount`, which already reflect the quoted rate." }, "executionSteps": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "action": { "enum": [ "erc20Approve" ], "type": "string" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "details": { "type": "object", "properties": { "token": { "type": "string" }, "spender": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Amount in decimal token units, ex. `10.00`." } }, "required": [ "token", "spender", "amount" ] }, "transaction": { "type": "object", "properties": { "from": { "type": "string", "description": "The sender's address." }, "to": { "type": "string", "description": "Contract to call." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "description": "Native value in base units." } }, "required": [ "from", "to", "data", "value" ] } }, "required": [ "action", "chain", "details", "transaction" ], "title": "ERC-20 Approve" }, { "type": "object", "properties": { "action": { "enum": [ "relayDepositErc20" ], "type": "string" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "transaction": { "type": "object", "properties": { "from": { "type": "string", "description": "The sender's address." }, "to": { "type": "string", "description": "Contract to call." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "description": "Native value in base units." } }, "required": [ "from", "to", "data", "value" ] } }, "required": [ "action", "chain", "transaction" ], "title": "Relay Deposit" }, { "type": "object", "properties": { "action": { "enum": [ "relayTransferAndMulticall" ], "type": "string" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Public API network identifier." }, "transaction": { "type": "object", "properties": { "from": { "type": "string", "description": "The sender's address." }, "to": { "type": "string", "description": "Contract to call." }, "data": { "type": "string", "description": "Calldata." }, "value": { "type": "string", "description": "Native value in base units." } }, "required": [ "from", "to", "data", "value" ] } }, "required": [ "action", "chain", "transaction" ], "title": "Relay Transfer + Multicall" } ] }, "minItems": 1, "description": "Ordered steps the caller executes in turn to fulfill the quote. `erc20Approve` appears only when the sender's existing allowance is insufficient. New `action` values may be added; tolerate unknown ones." }, "transactionId": { "type": "string", "format": "uuid", "description": "Poll GET /v0/transactions/{txnId} with this. 404 until the deposit is observed." } }, "required": [ "id", "provider", "createdAt", "expiresAt", "sender", "receiver", "senderAmount", "receiverAmount", "slippageBps", "fees", "executionSteps", "transactionId" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `not_found`: Resource not found.\n- `quote_not_found`: Quote not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found_quote_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/routes": { "post": { "operationId": "routes.create", "summary": "Create a route for a fiat ↔ stablecoin flow", "tags": [ "routes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "from": { "type": "object", "properties": { "currency": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Source currency. `usd` (wire), or any accepted token." } }, "required": [ "currency" ] }, "to": { "type": "object", "properties": { "currency": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Destination currency. `usd` (wire), or any accepted token." }, "accountId": { "type": "string", "format": "uuid" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Destination chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." } }, "required": [ "currency", "accountId" ] } }, "required": [ "from", "to" ] } } } }, "responses": { "200": { "description": "The route already existed, so nothing was created and the stored route is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deterministic route UUID; same canonical inputs always derive the same id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-set label, or null when unset." }, "createdAt": { "type": "string", "format": "date-time" }, "direction": { "enum": [ "mint-fiat", "mint-stablecoin", "redeem-fiat", "redeem-stablecoin" ], "type": "string", "description": "Which of the four flows this route is." }, "to": { "type": "object", "properties": { "currency": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "accountId": { "type": "string", "format": "uuid" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." } }, "required": [ "currency", "accountId" ] }, "instructions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "memo": { "type": "string", "description": "Memo / reference field that uniquely identifies the route on the inbound wire." }, "beneficiaryName": { "type": "string" }, "beneficiaryAddress": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "bankAddress": { "type": "string" }, "swiftCode": { "type": "string" }, "routingNumber": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies this wire instruction accepts" } }, "required": [ "memo", "beneficiaryName", "beneficiaryAddress", "accountNumber", "bankName", "bankAddress", "routingNumber", "supportedCurrencies" ] }, { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." }, "depositAddress": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies the deposit address accepts" } }, "required": [ "chain", "depositAddress", "supportedCurrencies" ] } ] }, "minItems": 1, "description": "Next-step instructions. Mint-fiat: one wire instruction with memo + beneficiary. On-chain directions: one deposit address per supported chain, alphabetical by chain." } }, "required": [ "id", "createdAt", "direction", "to", "instructions" ] } } } }, "201": { "description": "Route created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deterministic route UUID; same canonical inputs always derive the same id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-set label, or null when unset." }, "createdAt": { "type": "string", "format": "date-time" }, "direction": { "enum": [ "mint-fiat", "mint-stablecoin", "redeem-fiat", "redeem-stablecoin" ], "type": "string", "description": "Which of the four flows this route is." }, "to": { "type": "object", "properties": { "currency": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "accountId": { "type": "string", "format": "uuid" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." } }, "required": [ "currency", "accountId" ] }, "instructions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "memo": { "type": "string", "description": "Memo / reference field that uniquely identifies the route on the inbound wire." }, "beneficiaryName": { "type": "string" }, "beneficiaryAddress": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "bankAddress": { "type": "string" }, "swiftCode": { "type": "string" }, "routingNumber": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies this wire instruction accepts" } }, "required": [ "memo", "beneficiaryName", "beneficiaryAddress", "accountNumber", "bankName", "bankAddress", "routingNumber", "supportedCurrencies" ] }, { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." }, "depositAddress": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies the deposit address accepts" } }, "required": [ "chain", "depositAddress", "supportedCurrencies" ] } ] }, "minItems": 1, "description": "Next-step instructions. Mint-fiat: one wire instruction with memo + beneficiary. On-chain directions: one deposit address per supported chain, alphabetical by chain." } }, "required": [ "id", "createdAt", "direction", "to", "instructions" ] } } } }, "400": { "description": "- `chain_unsupported`: The requested chain is not supported.\n- `currency_unsupported`: The requested currency is not supported.\n- `direction_unsupported`: The requested route direction is not supported.\n- `parameter_invalid`: One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_chain_unsupported_currency_unsupported_direction_unsupported_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `account_not_found`: Account not found.\n- `not_found`: Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_account_not_found_not_found" } } } }, "409": { "description": "A route with these parameters exists but cannot be served. Contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_409_route_already_exists" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } }, "503": { "description": "Route creation temporarily unavailable. Please retry shortly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_503_route_creation_unavailable" } } } } }, "security": [ { "sessionJwt": [] } ] }, "get": { "operationId": "routes.get", "summary": "List the caller's routes", "tags": [ "routes" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor. Pass the `nextCursor` from the previous response; omit to fetch the first page." }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque pagination cursor. Pass the `nextCursor` from the previous response; omit to fetch the first page." }, { "name": "limit", "in": "query", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200, "description": "Page size. Defaults to 50; capped at 200." }, "allowEmptyValue": true, "allowReserved": true, "description": "Page size. Defaults to 50; capped at 200." }, { "name": "fromCurrency", "in": "query", "schema": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Return only routes that accept this currency on deposit, matched against the instructions' `supportedCurrencies`." }, "allowEmptyValue": true, "allowReserved": true, "description": "Return only routes that accept this currency on deposit, matched against the instructions' `supportedCurrencies`." }, { "name": "direction", "in": "query", "schema": { "type": "array", "items": { "enum": [ "mint-fiat", "mint-stablecoin", "redeem-fiat", "redeem-stablecoin" ], "type": "string" }, "minItems": 1, "description": "Return only routes in any of these directions, comma-separated. Omit for every direction the caller can read. This is how 'every redeem regardless of token' is spelled: `direction=redeem-fiat,redeem-stablecoin`." }, "style": "form", "explode": false, "allowEmptyValue": true, "allowReserved": true, "description": "Return only routes in any of these directions, comma-separated. Omit for every direction the caller can read. This is how 'every redeem regardless of token' is spelled: `direction=redeem-fiat,redeem-stablecoin`." }, { "name": "toAccountId", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Return only routes pointing at this registered account. A well-formed id belonging to another organization, or to nothing, returns an empty page rather than an error." }, "allowEmptyValue": true, "allowReserved": true, "description": "Return only routes pointing at this registered account. A well-formed id belonging to another organization, or to nothing, returns an empty page rather than an error." }, { "name": "toChain", "in": "query", "schema": { "type": "array", "items": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string" }, "minItems": 1, "description": "Return only routes landing on any of these chains, comma-separated. Fiat and wire destinations carry no chain and are never matched by this filter." }, "style": "form", "explode": false, "allowEmptyValue": true, "allowReserved": true, "description": "Return only routes landing on any of these chains, comma-separated. Fiat and wire destinations carry no chain and are never matched by this filter." }, { "name": "toCurrency", "in": "query", "schema": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Return only routes with this destination currency." }, "allowEmptyValue": true, "allowReserved": true, "description": "Return only routes with this destination currency." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deterministic route UUID; same canonical inputs always derive the same id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-set label, or null when unset." }, "createdAt": { "type": "string", "format": "date-time" }, "direction": { "enum": [ "mint-fiat", "mint-stablecoin", "redeem-fiat", "redeem-stablecoin" ], "type": "string", "description": "Which of the four flows this route is." }, "to": { "type": "object", "properties": { "currency": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "accountId": { "type": "string", "format": "uuid" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." } }, "required": [ "currency", "accountId" ] }, "instructions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "memo": { "type": "string", "description": "Memo / reference field that uniquely identifies the route on the inbound wire." }, "beneficiaryName": { "type": "string" }, "beneficiaryAddress": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "bankAddress": { "type": "string" }, "swiftCode": { "type": "string" }, "routingNumber": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies this wire instruction accepts" } }, "required": [ "memo", "beneficiaryName", "beneficiaryAddress", "accountNumber", "bankName", "bankAddress", "routingNumber", "supportedCurrencies" ] }, { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." }, "depositAddress": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies the deposit address accepts" } }, "required": [ "chain", "depositAddress", "supportedCurrencies" ] } ] }, "minItems": 1, "description": "Next-step instructions. Mint-fiat: one wire instruction with memo + beneficiary. On-chain directions: one deposit address per supported chain, alphabetical by chain." } }, "required": [ "id", "createdAt", "direction", "to", "instructions" ] }, "description": "Page of routes, newest first, tie-broken by id." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Pass back verbatim as the `cursor` query param to fetch the next page; null when no more results." } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/routes/{routeId}": { "get": { "operationId": "routes.getById", "summary": "Get a single route by id", "tags": [ "routes" ], "parameters": [ { "name": "routeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deterministic route UUID; same canonical inputs always derive the same id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "User-set label, or null when unset." }, "createdAt": { "type": "string", "format": "date-time" }, "direction": { "enum": [ "mint-fiat", "mint-stablecoin", "redeem-fiat", "redeem-stablecoin" ], "type": "string", "description": "Which of the four flows this route is." }, "to": { "type": "object", "properties": { "currency": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "accountId": { "type": "string", "format": "uuid" }, "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." } }, "required": [ "currency", "accountId" ] }, "instructions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "memo": { "type": "string", "description": "Memo / reference field that uniquely identifies the route on the inbound wire." }, "beneficiaryName": { "type": "string" }, "beneficiaryAddress": { "type": "string" }, "accountNumber": { "type": "string" }, "bankName": { "type": "string" }, "bankAddress": { "type": "string" }, "swiftCode": { "type": "string" }, "routingNumber": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies this wire instruction accepts" } }, "required": [ "memo", "beneficiaryName", "beneficiaryAddress", "accountNumber", "bankName", "bankAddress", "routingNumber", "supportedCurrencies" ] }, { "type": "object", "properties": { "chain": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Route chain (kebab-case). Restricted to chains Agora supports for routes (EVM + Solana)." }, "depositAddress": { "type": "string" }, "supportedCurrencies": { "type": "array", "items": { "enum": [ "ausd", "rnusd", "usdi", "usd", "ctk" ], "type": "string", "description": "Currency identifier." }, "minItems": 1, "description": "Currencies the deposit address accepts" } }, "required": [ "chain", "depositAddress", "supportedCurrencies" ] } ] }, "minItems": 1, "description": "Next-step instructions. Mint-fiat: one wire instruction with memo + beneficiary. On-chain directions: one deposit address per supported chain, alphabetical by chain." } }, "required": [ "id", "createdAt", "direction", "to", "instructions" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `not_found`: Resource not found.\n- `route_not_found`: Route not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found_route_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/transactions/{txnId}": { "get": { "operationId": "transactions.getById", "summary": "Get a single settled transaction by id, with its per-leg breakdown", "tags": [ "transactions" ], "parameters": [ { "name": "txnId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this transaction; pass to the detail endpoint to fetch legs." }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why a `tokenConversion` failed: `BLOCKED_WALLET`, `EXPIRED`, `INSUFFICIENT_FUNDS`, `OTHER`, `PROVIDER_UNAVAILABLE`, or `SLIPPAGE`. Null unless `type` is `tokenConversion` and `status` is `failed`. Open enum; tolerate unknown values." }, "initiatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the first leg." }, "isInstantSettlement": { "type": "boolean", "description": "True if this transaction used Agora's instant-settlement path rather than standard settlement." }, "legCount": { "type": "integer", "description": "Number of customer-facing legs in this transaction." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a bank account.", "enum": [ "bank" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account number. Null when unknown." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the financial institution, when known." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "accountNumber", "bankName", "name", "amounts" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a blockchain address.", "enum": [ "wallet" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain address, EIP-55 checksummed for EVM. Public on-chain data, returned in full. Null when unknown." }, "chain": { "type": "string", "description": "Chain the address is on, as the public-API network id (e.g. `ethereum`, `base`). Non-public/historical chains fall back to the raw chain id. Treated as an open enum; tolerate unknown values." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "address", "chain", "name", "amounts" ] } ], "description": "The counterparty receiving value, with the totals it received." }, "refundFailureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why returning a failed `tokenConversion`'s deposit also failed, so it will not come back on its own: `AMOUNT_TOO_LOW`, `MANUAL_REVIEW`, or `OTHER`. Null unless `type` is `tokenConversion` and `status` is `failed`. Open enum; tolerate unknown values." }, "settledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO-8601 timestamp when the transaction settled. Null until settled." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a bank account.", "enum": [ "bank" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account number. Null when unknown." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the financial institution, when known." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "accountNumber", "bankName", "name", "amounts" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a blockchain address.", "enum": [ "wallet" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain address, EIP-55 checksummed for EVM. Public on-chain data, returned in full. Null when unknown." }, "chain": { "type": "string", "description": "Chain the address is on, as the public-API network id (e.g. `ethereum`, `base`). Non-public/historical chains fall back to the raw chain id. Treated as an open enum; tolerate unknown values." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "address", "chain", "name", "amounts" ] } ], "description": "The counterparty sending value, with the totals it sent." }, "status": { "type": "string", "description": "Lifecycle status. Always `settled` unless `type` is `tokenConversion`. A `tokenConversion` starts `pending` (deposit received, conversion not yet sent), moves to `submitted` (conversion sent on the destination chain), and ends `settled`, `refunded` (deposit returned), or `failed` (see `failureReason` and `refundFailureReason`). A `failed` conversion can still move to `settled` or `refunded`. Open enum; tolerate unknown values." }, "type": { "type": "string", "description": "Customer-facing transaction type: `mint`, `redeem`, `bridge`, `reward`, `return`, or `tokenConversion`. Treated as an open enum; tolerate unknown values." }, "legs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this leg." }, "amount": { "type": "string", "description": "Decimal amount moved on this leg, as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`. Treated as an open enum; tolerate unknown values." }, "detail": { "anyOf": [ { "type": "object", "properties": { "type": { "description": "Discriminator: the leg settled as an internal book transfer.", "enum": [ "bookTransfer" ], "type": "string" }, "confirmationNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Book-transfer confirmation number. Null when not yet known." } }, "required": [ "type", "confirmationNumber" ], "description": "Book-transfer leg detail." }, { "type": "object", "properties": { "type": { "description": "Discriminator: the leg is a manual fee entry.", "enum": [ "fee" ], "type": "string" } }, "required": [ "type" ], "description": "Fee leg detail. A manual accounting entry with no rail identifier." }, { "type": "object", "properties": { "type": { "description": "Discriminator: the leg settled over an instant-payment rail.", "enum": [ "instantPayment" ], "type": "string" }, "confirmationNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Instant-payment confirmation number. Null when not yet known." } }, "required": [ "type", "confirmationNumber" ], "description": "Instant-payment leg detail." }, { "type": "object", "properties": { "type": { "description": "Discriminator: the leg settled on-chain.", "enum": [ "token" ], "type": "string" }, "transactionHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain transaction hash. Null when not yet known." } }, "required": [ "type", "transactionHash" ], "description": "On-chain (token) leg detail." }, { "type": "object", "properties": { "type": { "description": "Discriminator: the leg settled over a wire transfer.", "enum": [ "wire" ], "type": "string" }, "imad": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Fedwire IMAD (Input Message Accountability Data) identifying the wire. Null when not yet known." } }, "required": [ "type", "imad" ], "description": "Wire-transfer leg detail." } ], "description": "Rail-specific identifiers for the leg, shaped by the settlement rail." }, "direction": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "description": "Direction of value movement relative to the customer: `INBOUND` (value arrives) or `OUTBOUND` (value leaves)." }, "occurredAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp when this leg occurred." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a bank account.", "enum": [ "bank" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account number. Null when unknown." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the financial institution, when known." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." } }, "required": [ "kind", "accountId", "accountNumber", "bankName", "name" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a blockchain address.", "enum": [ "wallet" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain address, EIP-55 checksummed for EVM. Public on-chain data, returned in full. Null when unknown." }, "chain": { "type": "string", "description": "Chain the address is on, as the public-API network id (e.g. `ethereum`, `base`). Non-public/historical chains fall back to the raw chain id. Treated as an open enum; tolerate unknown values." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." } }, "required": [ "kind", "accountId", "address", "chain", "name" ] } ], "description": "The counterparty receiving value on this leg." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a bank account.", "enum": [ "bank" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account number. Null when unknown." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the financial institution, when known." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." } }, "required": [ "kind", "accountId", "accountNumber", "bankName", "name" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a blockchain address.", "enum": [ "wallet" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain address, EIP-55 checksummed for EVM. Public on-chain data, returned in full. Null when unknown." }, "chain": { "type": "string", "description": "Chain the address is on, as the public-API network id (e.g. `ethereum`, `base`). Non-public/historical chains fall back to the raw chain id. Treated as an open enum; tolerate unknown values." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." } }, "required": [ "kind", "accountId", "address", "chain", "name" ] } ], "description": "The counterparty sending value on this leg." } }, "required": [ "id", "amount", "currency", "detail", "direction", "occurredAt", "recipient", "source" ], "description": "A single customer-facing leg of a transaction." }, "description": "The customer-facing legs that make up this transaction." } }, "required": [ "id", "failureReason", "initiatedAt", "isInstantSettlement", "legCount", "recipient", "refundFailureReason", "settledAt", "source", "status", "type", "legs" ], "description": "A single settled transaction with its per-leg breakdown." } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `not_found`: Resource not found.\n- `transaction_not_found`: Transaction not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found_transaction_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/transactions": { "get": { "operationId": "transactions.list", "summary": "List the caller's settled transactions", "tags": [ "transactions" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string", "description": "Opaque pagination cursor. Pass the `nextCursor` from the previous response; omit to fetch the first page." }, "allowEmptyValue": true, "allowReserved": true, "description": "Opaque pagination cursor. Pass the `nextCursor` from the previous response; omit to fetch the first page." }, { "name": "limit", "in": "query", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200, "description": "Page size. Defaults to 50; capped at 200." }, "allowEmptyValue": true, "allowReserved": true, "description": "Page size. Defaults to 50; capped at 200." }, { "name": "initiatedAt.gt", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Exclusive lower bound on the transaction's initiation time, as an ISO-8601 timestamp." }, "allowEmptyValue": true, "allowReserved": true, "description": "Exclusive lower bound on the transaction's initiation time, as an ISO-8601 timestamp." }, { "name": "initiatedAt.gte", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Inclusive lower bound on the transaction's initiation time, as an ISO-8601 timestamp." }, "allowEmptyValue": true, "allowReserved": true, "description": "Inclusive lower bound on the transaction's initiation time, as an ISO-8601 timestamp." }, { "name": "initiatedAt.lt", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Exclusive upper bound on the transaction's initiation time, as an ISO-8601 timestamp. Pairs with `initiatedAt.gte` to select a period without depending on its last instant." }, "allowEmptyValue": true, "allowReserved": true, "description": "Exclusive upper bound on the transaction's initiation time, as an ISO-8601 timestamp. Pairs with `initiatedAt.gte` to select a period without depending on its last instant." }, { "name": "initiatedAt.lte", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Inclusive upper bound on the transaction's initiation time, as an ISO-8601 timestamp." }, "allowEmptyValue": true, "allowReserved": true, "description": "Inclusive upper bound on the transaction's initiation time, as an ISO-8601 timestamp." }, { "name": "isInstantSettlement", "in": "query", "schema": { "enum": [ "true", "false" ], "type": "string", "description": "Return only transactions whose settlement path matches. `true` is the instant-settlement path; `false` is standard settlement, which includes movement types that have no settlement path of their own, such as rewards and returns." }, "allowEmptyValue": true, "allowReserved": true, "description": "Return only transactions whose settlement path matches. `true` is the instant-settlement path; `false` is standard settlement, which includes movement types that have no settlement path of their own, such as rewards and returns." }, { "name": "recipientChain", "in": "query", "schema": { "type": "array", "items": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string" }, "minItems": 1, "description": "Return only transactions whose recipient received value on these networks, comma-separated." }, "style": "form", "explode": false, "allowEmptyValue": true, "allowReserved": true, "description": "Return only transactions whose recipient received value on these networks, comma-separated." }, { "name": "sourceChain", "in": "query", "schema": { "type": "array", "items": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string" }, "minItems": 1, "description": "Return only transactions whose source sent value on these networks, comma-separated." }, "style": "form", "explode": false, "allowEmptyValue": true, "allowReserved": true, "description": "Return only transactions whose source sent value on these networks, comma-separated." }, { "name": "type", "in": "query", "schema": { "type": "array", "items": { "enum": [ "bridge", "mint", "redeem", "return", "reward", "tokenConversion" ], "type": "string" }, "minItems": 1, "description": "Return only these movement types, comma-separated." }, "style": "form", "explode": false, "allowEmptyValue": true, "allowReserved": true, "description": "Return only these movement types, comma-separated." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable UUID identifying this transaction; pass to the detail endpoint to fetch legs." }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why a `tokenConversion` failed: `BLOCKED_WALLET`, `EXPIRED`, `INSUFFICIENT_FUNDS`, `OTHER`, `PROVIDER_UNAVAILABLE`, or `SLIPPAGE`. Null unless `type` is `tokenConversion` and `status` is `failed`. Open enum; tolerate unknown values." }, "initiatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the first leg." }, "isInstantSettlement": { "type": "boolean", "description": "True if this transaction used Agora's instant-settlement path rather than standard settlement." }, "legCount": { "type": "integer", "description": "Number of customer-facing legs in this transaction." }, "recipient": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a bank account.", "enum": [ "bank" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account number. Null when unknown." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the financial institution, when known." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "accountNumber", "bankName", "name", "amounts" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a blockchain address.", "enum": [ "wallet" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain address, EIP-55 checksummed for EVM. Public on-chain data, returned in full. Null when unknown." }, "chain": { "type": "string", "description": "Chain the address is on, as the public-API network id (e.g. `ethereum`, `base`). Non-public/historical chains fall back to the raw chain id. Treated as an open enum; tolerate unknown values." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "address", "chain", "name", "amounts" ] } ], "description": "The counterparty receiving value, with the totals it received." }, "refundFailureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why returning a failed `tokenConversion`'s deposit also failed, so it will not come back on its own: `AMOUNT_TOO_LOW`, `MANUAL_REVIEW`, or `OTHER`. Null unless `type` is `tokenConversion` and `status` is `failed`. Open enum; tolerate unknown values." }, "settledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "ISO-8601 timestamp when the transaction settled. Null until settled." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a bank account.", "enum": [ "bank" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "accountNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bank account number. Null when unknown." }, "bankName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name of the financial institution, when known." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "accountNumber", "bankName", "name", "amounts" ] }, { "type": "object", "properties": { "kind": { "description": "Discriminator: the counterparty is a blockchain address.", "enum": [ "wallet" ], "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID of the customer account this counterparty maps to (same id as `/v0/accounts`), or null when the address is not a known account (e.g. the Agora side). Bank counterparties currently always return null; bank-to-account linkage is not derived yet." }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "On-chain address, EIP-55 checksummed for EVM. Public on-chain data, returned in full. Null when unknown." }, "chain": { "type": "string", "description": "Chain the address is on, as the public-API network id (e.g. `ethereum`, `base`). Non-public/historical chains fall back to the raw chain id. Treated as an open enum; tolerate unknown values." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display label for the counterparty. The Agora side of a leg is labelled `\"Agora\"`." }, "amounts": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal amount as a string (avoids floating-point precision loss)." }, "currency": { "type": "string", "description": "Currency code, e.g. `usd`, `ausd`, `usdc`." } }, "required": [ "amount", "currency" ], "description": "A per-currency amount moved on one side of the transaction." }, "description": "Per-currency totals moved on this side of the transaction, one entry per currency." } }, "required": [ "kind", "accountId", "address", "chain", "name", "amounts" ] } ], "description": "The counterparty sending value, with the totals it sent." }, "status": { "type": "string", "description": "Lifecycle status. Always `settled` unless `type` is `tokenConversion`. A `tokenConversion` starts `pending` (deposit received, conversion not yet sent), moves to `submitted` (conversion sent on the destination chain), and ends `settled`, `refunded` (deposit returned), or `failed` (see `failureReason` and `refundFailureReason`). A `failed` conversion can still move to `settled` or `refunded`. Open enum; tolerate unknown values." }, "type": { "type": "string", "description": "Customer-facing transaction type: `mint`, `redeem`, `bridge`, `reward`, `return`, or `tokenConversion`. Treated as an open enum; tolerate unknown values." } }, "required": [ "id", "failureReason", "initiatedAt", "isInstantSettlement", "legCount", "recipient", "refundFailureReason", "settledAt", "source", "status", "type" ], "description": "Transaction summary. Fetch the detail endpoint with `id` for per-leg detail." }, "description": "Page of transactions, newest first (by initiated time, tie-broken by id)." }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor for the next page. Pass back verbatim as the `cursor` query param; null when no more results." } }, "required": [ "data", "nextCursor" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/sandbox/faucet": { "post": { "operationId": "sandbox.faucet", "summary": "Send testnet CTK to an address", "description": "Sandbox only. Sends 1,000 testnet CTK to the address, to fund deposits to sandbox routes. Send it to a wallet you control, then deposit from that wallet: CTK sent straight to a route's deposit address is not paid out. There is no per-organization limit. The transfer is asynchronous and usually arrives within a minute.", "tags": [ "sandbox" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "EVM address to receive the CTK. It does not need to be a registered account." }, "network": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Testnet to send the CTK on." } }, "required": [ "address", "network" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "description": "The address the CTK is sent to, lowercased." }, "amount": { "type": "string", "description": "CTK sent, as a decimal string." }, "currency": { "enum": [ "ctk" ], "type": "string" }, "network": { "enum": [ "avalanche-fuji", "ethereum-sepolia" ], "type": "string", "description": "Blockchain network identifier. Use this to filter or group supply data by chain. Values are stable; new networks may be added but existing ones will not be renamed." }, "sandbox": { "description": "Always true: this endpoint exists only in the sandbox.", "enum": [ true ] }, "status": { "description": "The transfer is sent shortly after this response. Check the address's CTK balance to see it arrive.", "enum": [ "queued" ], "type": "string" } }, "required": [ "address", "amount", "currency", "network", "sandbox", "status" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } }, "/v0/sandbox/wires": { "post": { "operationId": "sandbox.wires", "summary": "Simulate a wire into a mint route", "description": "Sandbox only. Simulates an incoming USD wire into one of your mint-fiat routes. The route's token is sent to its destination wallet on testnet, and the mint appears in your transactions. No real money moves.", "tags": [ "sandbox" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,2})?$", "description": "USD the simulated wire sends, as a decimal string. The route pays the same amount of its token." }, "routeId": { "type": "string", "format": "uuid", "description": "The mint-fiat route the wire is sent to." }, "sourceAccountId": { "type": "string", "format": "uuid", "description": "A bank account registered to your organization (`POST /v0/accounts`, kind `bank`). The wire comes from it." } }, "required": [ "amount", "routeId", "sourceAccountId" ] } } } }, "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "description": "USD sent, as a decimal string." }, "id": { "type": "string", "format": "uuid", "description": "The simulated wire's id." }, "routeId": { "type": "string", "format": "uuid" }, "sandbox": { "description": "Always true: this endpoint exists only in the sandbox.", "enum": [ true ] }, "status": { "description": "The wire is recorded and the route's token sent shortly after this response. Poll `GET /v0/transactions` to see the mint.", "enum": [ "queued" ], "type": "string" } }, "required": [ "amount", "id", "routeId", "sandbox", "status" ] } } } }, "400": { "description": "One or more request parameters are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_400_parameter_invalid" } } } }, "401": { "description": "Authentication is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_401_unauthorized" } } } }, "403": { "description": "- `account_not_eligible`: The account is not eligible for this request.\n- `account_not_provisioned`: The account is not provisioned for this product.\n- `account_verification_pending`: Account verification for this product is pending.\n- `forbidden`: Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden" } } } }, "404": { "description": "- `account_not_found`: Account not found.\n- `not_found`: Resource not found.\n- `route_not_found`: Route not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_404_account_not_found_not_found_route_not_found" } } } }, "429": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_429_rate_limit_exceeded" } } } }, "500": { "description": "An unexpected error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse_500_internal_error" } } } } }, "security": [ { "sessionJwt": [] } ] } } }, "externalDocs": { "description": "Agora API Reference", "url": "https://docs.agora.finance/api" }, "components": { "schemas": { "ErrorResponse_400_chain_unsupported_currency_unsupported_direction_unsupported_parameter_invalid": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "chain_unsupported", "currency_unsupported", "direction_unsupported", "parameter_invalid" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "issues" ] } } }, "ErrorResponse_400_chain_unsupported_currency_unsupported_parameter_invalid": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "chain_unsupported", "currency_unsupported", "parameter_invalid" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "issues" ] } } }, "ErrorResponse_400_entitlement_not_requestable_parameter_invalid": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "entitlement_not_requestable", "parameter_invalid" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "issues" ] } } }, "ErrorResponse_400_parameter_invalid": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "parameter_invalid" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "issues": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "message" ] } } }, "required": [ "issues" ] } } }, "ErrorResponse_401_unauthorized": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "reason": { "enum": [ "invalid_token", "key_not_provisioned", "missing_claim", "missing_header", "token_expired", "token_paused", "token_revoked", "unknown_tenant" ], "type": "string" } }, "required": [ "reason" ] } } }, "ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "account_not_eligible", "account_not_provisioned", "account_verification_pending", "forbidden" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_403_account_not_eligible_account_not_provisioned_account_verification_pending_forbidden_wallet_blocked": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "account_not_eligible", "account_not_provisioned", "account_verification_pending", "forbidden", "wallet_blocked" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "reason": { "enum": [ "BLOCKED_WALLET" ], "type": "string" } }, "required": [ "reason" ] } } }, "ErrorResponse_404_account_not_found_not_found": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "account_not_found", "not_found" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_404_account_not_found_not_found_route_not_found": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "account_not_found", "not_found", "route_not_found" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_404_not_found": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_404_not_found_quote_not_found": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "not_found", "quote_not_found" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_404_not_found_route_not_found": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "not_found", "route_not_found" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_404_not_found_transaction_not_found": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "not_found", "transaction_not_found" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_409_account_already_exists": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "account_already_exists" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_409_route_already_exists": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "route_already_exists" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" }, "context": { "type": "object", "properties": { "routeId": { "type": "string", "format": "uuid" } }, "required": [ "routeId" ] } } }, "ErrorResponse_429_rate_limit_exceeded": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "rate_limit_exceeded" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_500_internal_error": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "internal_error" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_503_route_creation_unavailable": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "route_creation_unavailable" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } }, "ErrorResponse_503_service_unavailable": { "type": "object", "required": [ "code", "docs_url", "message" ], "properties": { "code": { "type": "string", "enum": [ "service_unavailable" ] }, "docs_url": { "type": "string", "example": "https://docs.agora.finance/api/errors" }, "message": { "type": "string" } } } }, "securitySchemes": { "accessKey": { "type": "http", "scheme": "bearer", "description": "Agora access key (cleartext), sent as `Authorization: Bearer `. Used only by POST /v0/auth/token to mint a session JWT." }, "sessionJwt": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Session JWT from POST /v0/auth/token, sent as `Authorization: Bearer `." } } } }