Skip to navigation

Sandbox Overview

Build and test against the Agora Public API on testnets.
← Switch to the Production API

This is the sandbox. It runs on testnets only. Never send real money or real tokens to an address or bank account the sandbox returns.

The sandbox is subject to the Beta Features section of our Terms of Use.

Use the sandbox to try Agora’s APIs before you have a production account, or to test changes without touching your live integration. It runs the same /v0 endpoints as production, so the code you write here carries over with a few config changes. See Move to production.

Agora sets up your sandbox organization and sends you its API key. To request access, fill out this form.

Download Sandbox OpenAPI spec

Base URL

All sandbox endpoints are served from https://api.sandbox.agora.finance.

Chains and currencies

Sandbox values
Chainsavalanche-fuji, ethereum-sepolia
Wallet address formatethereum
Tokensausd, ctk
Fiatusd, simulated only

Anything else is rejected with a 400. See Testnet Tokens for addresses and faucets.

No US dollars move in the sandbox. Bank accounts and routes accept usd so you can build fiat flows, but the sandbox never sends or receives a wire. It simulates them instead. Any bank details it returns are fake. Never send real money to them.

Tokens sent to the wrong place are lost. Sandbox deposit addresses are keyless, so no one can return them. Send only the route’s source token. Send faucet CTK to your own wallet first, never straight to a deposit address.

Conventions

A few conventions hold across the API:

  • Monetary values are decimal strings, not numbers. Amount fields are strings like "987654321.654321". AUSD carries six decimals of precision; representing an amount as a JSON number would silently truncate it. Parse with a decimal library (decimal.Decimal in Python, BigNumber.js in JavaScript, rust_decimal in Rust). This follows industry standard practice (Circle, Stripe).
  • Every response carries a Request-Id header. Capture it in your logs — it’s how Agora support traces a specific request end-to-end.

Endpoint-specific response details — such as the per-chain shape and partial-state behavior of /v0/metrics — are documented on each endpoint under Endpoints.

Filtering list endpoints

GET /v0/accounts, GET /v0/routes, and GET /v0/transactions accept filters alongside cursor and limit. The grammar is the same on all three:

  • Filters combine with AND. Every filter you send must hold for a record to appear.
  • Multi-value filters take one comma-separated parameter: ?network=avalanche-fuji,ethereum-sepolia, not a repeated ?network=avalanche-fuji&network=ethereum-sepolia, which is rejected.
  • Date ranges use dotted bounds: .gte / .gt for the lower bound, .lte / .lt for the upper, as in ?createdAt.gte=2026-03-01T00:00:00Z&createdAt.lt=2026-04-01T00:00:00Z. Timestamps are ISO-8601 and must carry a zone (Z or an offset). The exclusive bounds let you select a period without naming its last instant.
  • A filter is never silently dropped. An unknown parameter, an unknown range operator, a value outside the accepted set, an empty value, two bounds on the same side, or a range nothing can satisfy all return 400 parameter_invalid with the offending parameter named in context.issues.

A filter that is valid but matches nothing returns 200 with an empty data array.

Move to production

Before you can get production API keys, your organization needs to complete Agora’s onboarding, including KYB and KYC checks.

When you’re ready for production, change three things:

  1. Point your client at https://api.agora.finance.
  2. Swap in a production API key, created from the Agora dashboard.
  3. Replace sandbox chain and currency values with their production equivalents, such as ethereum-sepolia to ethereum and ctk to usdc.