Skip to main content
A transaction is the durable record of one financial leg on an account. Payments and deposits are what happen; transactions are what remains, and they are what reconciliation reads.

​
Each row names what produced it

sourceType names what produced the leg and sourceId identifies that object. When the leg belongs to a canonical Payment, paymentId carries it and financialLegKind says which leg this row is: collection, send_execution, settlement, fee_payout, refund or adjustment. One Payment therefore produces several rows, which is what lets a finance team tie gross, fee and net against each other.

​
List an account’s transactions

Rows come back newest first. There is no date-range filter: the list is paged, not queried by period, and Statements covers what to do about that. The cursor is opaque and ordering is stable, so paging a history twice returns the same sequence. Do not construct a cursor or read meaning out of one.
posted is a status a row can hold, but it is not accepted by the status filter. Filter on the other four, or read every page and select in your own code.

​
Only pending is non-terminal

reversed is an accounting correction, not an on-chain clawback. The underlying funds have usually already moved, so do not tell a customer money is coming back.

​
Direction belongs to the reader

A transfer between two accounts is one row both sides can read. Read perspective.direction, which reports sent, received, self or related for the account in the path, with perspective.counterpartyAccountId when the other side is known. The same value is repeated at the top level as direction. amount is stated from that perspective too. On a send, the sender sees the gross source debit and the recipient sees the net destination amount actually settled, so both sides reconcile without doing the arithmetic.

​
What a record contains

Always present: id, accountId, status, amount, description, sourceType, sourceId.

​
Off-ramp detail

A payout row carries offrampDetails, frozen at quote time and safe to print on a receipt. Account numbers appear as their last four characters only, and any field the provider did not return is null rather than absent. Account numbers appear as their last four characters only, and any field the provider did not return is null rather than absent. fiatAmount.amountAtomic can be null. When known at snapshot time, it is an exact integer string scaled by the supplied decimals; otherwise it is null. A collect_exact bank payout, for example, records confirmed crypto collection before the final fiat amount exists. assetCode and decimals are present either way. Show null as unavailable, never as zero. Preserve the reported precision: exact-input US bank payout evidence can contain six decimal places of USD. A completed collection or settlement row describes the crypto leg only. It does not mean the bank payout succeeded, and the frozen snapshot can keep an unknown amount after the payment moves on. For the payout result, read the row’s paymentId through GET /v2/payments/{paymentId}.

​
Read one transaction for its ledger entries

The detail read adds ledgerEntries: id, direction (debit or credit), amount and createdAt. They are scoped to the account you asked about, so they are that account’s side of the entry rather than the full balanced set. createdAt on a ledger entry is the one dated field the contract publishes against a movement.

​
Balances are reporting, not custody

GET /v2/accounts/{accountId}/balances returns an accounting projection over the same recorded activity. It reports balanceType: "recorded_activity_projection" and custodyScope: "not_a_custody_balance", and those two fields exist to stop one specific bug.
Never authorise a spend against it, never gate a withdrawal on it, and never render it as funds available. A sufficient-funds check written against this number passes when it should fail, rarely, in production, on a real customer.
activityTotals carries one entry per asset, always per chain and asset rather than one cross-chain figure:
  • netRecordedFlowAtomic is a signed cumulative net. It can be negative when a wallet or Vault funded outside Stableyard’s view makes a verified payment, and it can stay positive after value has settled out to a customer’s own wallet. Your parser must accept a leading minus sign.
  • reservedForVaultPaymentsAtomic is context about Vault payments in flight. It is presented alongside the net, never subtracted from it.
  • observedAt is when the projection last changed, not a heartbeat.
To know what can actually be spent, read the source: the wallet, the escrow, or the Vault’s spend usage.

Next: Statements

Turn these rows into a periodic statement for a customer.