Skip to navigation
Agora Public APIEndpointsTransactions

Overview

Transactions and their per-leg detail.

A transaction is a movement of value through Agora: a mint, a redeem, a bridge, a rewards payout, a returned transfer, or a stablecoin conversion. Each records a source, a recipient, and the per-currency totals that moved. The detail endpoint adds the legs behind it: the individual settlement steps, like an onchain transfer, a wire, or a book transfer.

  • GET /v0/transactions lists your transactions, newest first, with cursor pagination.
  • GET /v0/transactions/{txnId} returns one transaction plus its legs.

Types

A transaction’s type tells you what it did:

  • mint: fiat or stablecoin in, AUSD out.
  • redeem: AUSD in, fiat or stablecoin out.
  • bridge: AUSD moved between chains.
  • reward: a rewards payout.
  • return: a returned or reversed transfer.
  • tokenConversion: a stablecoin-to-stablecoin conversion executed from a Convert Stablecoins quote.

We will add new type values over time, so handle ones you don’t recognize gracefully. isInstantSettlement is true when the transaction took Agora’s instant-settlement path.

Status

For every type except tokenConversion, status is always settled: these are settled-only rows. 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. We will add further values over time, so handle ones you don’t recognize gracefully.

On a failed tokenConversion, failureReason says why the conversion failed (BLOCKED_WALLET, EXPIRED, INSUFFICIENT_FUNDS, PROVIDER_UNAVAILABLE, SLIPPAGE, or OTHER), and refundFailureReason is set when the deposit won’t come back on its own (AMOUNT_TOO_LOW, MANUAL_REVIEW, or OTHER). Treat both as open enums. Both are always null for every other type. initiatedAt is the first leg’s time; settledAt is when settlement completed, null until then.

Counterparties

The transaction and each of its legs carry a source and a recipient, each tagged by kind:

  • bank: carries bankName, accountNumber, and the name you registered the account under.
  • wallet: carries the checksummed address, the chain, and the name you registered the wallet under.

The non-customer side of a transfer is named "Agora" — except on a tokenConversion leg, where it’s the liquidity provider that filled the quote (e.g., "Relay"), not Agora itself. Each counterparty carries an accountId matching an account from GET /v0/accounts, or null when the account isn’t associated with your organization. Bank counterparties currently return null.

On the transaction itself (not its legs), source and recipient also carry amounts, the per-currency totals that moved on that side.

Legs

The detail endpoint adds a legs array, one entry per settlement step. Each leg has a decimal-string amount and currency, its own source and recipient, and:

  • direction: relative to the customer: INBOUND is value arriving, OUTBOUND is value leaving. On a tokenConversion, the deposit to the provider is OUTBOUND, and the fill or refund from the provider is INBOUND.
  • detail: rail-specific ids, keyed by type: token (onchain transactionHash), wire (Fedwire imad), bookTransfer (confirmationNumber), or instantPayment (confirmationNumber). A fee leg is a manual accounting entry, so its detail carries only the type.

A leg’s detail.type names the settlement rail (token, wire, …). The transaction-level type classifies the whole transaction (mint, redeem, …). Same field name, different values.

Filtering

GET /v0/transactions narrows the list by movement type, by sourceChain / recipientChain, by isInstantSettlement, and by an initiatedAt range. The grammar is shared across the list endpoints. See Filtering list endpoints.

The chain filters match the source and recipient the response reports, not every leg the transaction touched: a mint funded by wire has no source chain, so it matches on recipientChain only. isInstantSettlement=false covers standard settlement plus the types that have no settlement path of their own, such as reward and return.

Pagination

Both list responses return { data, nextCursor }:

  • data: the page, newest first.
  • nextCursor: an opaque cursor. Pass it back as the cursor query param for the next page; null when there are none.

Size the page with limit. Amounts are decimal strings, not numbers (see the API overview). Every endpoint needs authentication (see the Authentication guide); for errors, see the Error Reference.