> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentaos.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List transactions
> One unified list of everything that moved money on your account: inbound payments (from checkouts and payment links) and outbound sends, across every rail (card, SEPA bank transfer, stablecoins on-chain), in one feed. Only `confirmed` rows are returned: a pending or failed attempt never appears here; `status` on each item is always `confirmed`.
Only `confirmed` rows are returned. A pending or failed attempt never appears here. There's no `status` filter to request otherwise; `status` on each item is always `confirmed`.
This row carries additional internal ledger fields (settlement batch references, dispute markers, raw card-processor fee) beyond what's documented here. Treat any field not listed as forward-compatible and safe to ignore. Don't build logic against undocumented keys.
Every settled inbound transaction has a matching invoice.
Get notified the moment a transaction settles, instead of polling this list.
## OpenAPI
````yaml GET /gateway/all-transactions
openapi: 3.1.0
info:
title: AgentaOS Gateway API
version: 1.0.0
description: >-
The AgentaOS REST API: payment links, checkouts, subscriptions, customers,
invoices, and the unified transactions feed. This is the same API the
TypeScript SDK (`@agentaos/pay`) and the `agenta` CLI call underneath.
## Money model
- **Decimal currency units (`number`)**: a plain `amount` field (on a create
body, a Payment Link, a Checkout's `amount_override`, or an Invoice's
`amount`/`fiat_amount`/`tax_amount`) is in currency units. `49.99` means EUR
49.99, never cents.
- **Integer minor units (`number`)**: exactly one field breaks that rule:
`unitAmountMinor` on a Subscription. It is an integer count of the smallest
currency unit (`1999` means EUR 19.99), named with a `Minor` suffix
specifically so it is never confused with a plain `amount`. The `money`
object on Transactions and the `earnings` object on a retrieved Invoice are
also integer minor units, computed server-side.
- **String, on webhooks**: the `amount` inside a webhook payload's `data`
object is a string (e.g. `"49.99"`), since JSON numbers silently drop
trailing zeros and this value must round-trip exactly for accounting.
## Naming convention
Most response fields mirror the underlying database column and are
`snake_case` (`created_at`, `seller_mode`, `buyer_email`, ...). A small
number of computed convenience fields are camelCase with no snake_case
equivalent: `checkoutUrl` on Checkouts and Payment Links, `sellerMode` on
Payment Links specifically, `money` on Transactions, and `earnings` on a
single retrieved Invoice. Two resources (Subscriptions and Customers) are
fully camelCase end to end.
## Pagination
Every list endpoint takes `limit` and `offset` and returns `{ items, total,
hasMore }`. `hasMore` is computed server-side (`offset + items.length <
total`); never derive it client-side.
contact:
name: AgentaOS
url: https://agentaos.ai
license:
name: Proprietary
url: https://agentaos.ai
servers:
- url: https://api.agentaos.ai/api/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Payment Links
description: >-
Reusable, shareable payment products: a fixed amount and description
behind one URL.
- name: Checkouts
description: >-
One attempt to collect one payment, standalone or built from a payment
link. Wire path is `/gateway/sessions`; the SDK and CLI call this resource
"checkout".
- name: Subscriptions
description: >-
Merchant-side read and management surface for recurring plans. Created
automatically when a buyer pays a `type: subscription` payment link.
- name: Customers
description: 'Read-only surface: everyone who has paid you or been sent an invoice.'
- name: Invoices
description: >-
Every checkout issues an invoice. List, retrieve, void, export, and
download PDFs/receipts.
- name: Transactions
description: >-
The unified activity feed: every inbound payment and outbound send, across
every rail, in one list.
paths:
/gateway/all-transactions:
get:
tags:
- Transactions
summary: List transactions
description: >-
One unified list of everything that moved money on your account: inbound
payments (from checkouts and payment links) and outbound sends, across
every rail (card, SEPA bank transfer, stablecoins on-chain), in one
feed. Only `confirmed` rows are returned: a pending or failed attempt
never appears here; `status` on each item is always `confirmed`.
operationId: listTransactions
parameters:
- name: direction
in: query
required: false
schema:
type: string
enum:
- all
- inbound
- outbound
default: all
- $ref: '#/components/parameters/From'
- $ref: '#/components/parameters/To'
- $ref: '#/components/parameters/FiatCurrency'
- $ref: '#/components/parameters/NetworksFilter'
- $ref: '#/components/parameters/Limit5000'
- $ref: '#/components/parameters/Offset'
responses:
'200':
description: A page of transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionListResponse'
examples:
default:
$ref: '#/components/examples/TransactionListExample'
'401':
$ref: '#/components/responses/Unauthorized'
components:
parameters:
From:
name: from
in: query
required: false
description: ISO 8601 date or datetime, inclusive lower bound.
schema:
type: string
To:
name: to
in: query
required: false
description: ISO 8601 date or datetime, inclusive upper bound.
schema:
type: string
FiatCurrency:
name: fiatCurrency
in: query
required: false
description: Filter to rows settled/presented in this fiat currency.
schema:
type: string
enum:
- EUR
- USD
NetworksFilter:
name: networks
in: query
required: false
description: >-
Comma-separated CAIP-2 network IDs to filter by, e.g.
`eip155:8453,eip155:84532`. Ignored if your API key is network-scoped.
schema:
type: string
Limit5000:
name: limit
in: query
required: false
description: Items per page. Capped server-side at 5000.
schema:
type: integer
default: 20
minimum: 1
maximum: 5000
Offset:
name: offset
in: query
required: false
description: Number of items to skip, for the next page.
schema:
type: integer
default: 0
minimum: 0
schemas:
TransactionListResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Transaction'
total:
type: integer
hasMore:
type: boolean
required:
- items
- total
- hasMore
Transaction:
type: object
additionalProperties: true
description: >-
This row carries additional internal ledger fields (settlement batch
references, dispute markers, raw card-processor fee) beyond what's
documented here. Treat any undocumented field as forward-compatible and
safe to ignore.
properties:
id:
type: string
format: uuid
direction:
type: string
enum:
- inbound
- outbound
amount:
type: number
description: >-
Presentment amount, currency units, in
payment_token/settlement_token.
payment_token:
type: string
description: What the buyer paid with, e.g. EURC, card.
settlement_token:
type: string
description: What settled to your balance.
status:
type: string
const: confirmed
description: Always confirmed on this endpoint.
payment_method:
type:
- string
- 'null'
enum:
- card
- sepa
- bank_transfer
- bridge
- wallet
- null
description: How the buyer actually paid, independent of network.
payer_type:
type: string
enum:
- human
- agent
payer_address:
type:
- string
- 'null'
description: On-chain payer wallet. null for card/bank rails.
tx_hash:
type:
- string
- 'null'
description: null for card/bank rails, use vendor_reference there instead.
vendor_reference:
type:
- string
- 'null'
description: >-
Off-chain audit reference (card-processor payment reference, bank
reference). Mutually exclusive with tx_hash.
network:
type: string
description: CAIP-2 network ID for on-chain rails, or stripe for card/bank.
seller_of_record:
type: string
enum:
- aristokrates_ou
- merchant
description: >-
aristokrates_ou for a Merchant of Record card sale, merchant for
everything else.
invoice_id:
type:
- string
- 'null'
format: uuid
description: >-
The matching invoice, joined for convenience. null for outbound
rows.
payment_link_id:
type:
- string
- 'null'
format: uuid
session_id:
type:
- string
- 'null'
description:
type:
- string
- 'null'
created_at:
type: string
format: date-time
money:
$ref: '#/components/schemas/TransactionMoney'
required:
- id
- direction
- amount
- payment_token
- settlement_token
- status
- payment_method
- payer_type
- payer_address
- tx_hash
- vendor_reference
- network
- seller_of_record
- invoice_id
- payment_link_id
- session_id
- description
- created_at
- money
Error:
type: object
description: >-
Every non-2xx response is JSON in this shape. Every response (success or
error) also carries an `x-request-id` response header; send that header
on your request to have your own id echoed back, otherwise the server
mints one. On errors the same id is repeated in the `requestId` body
field.
properties:
statusCode:
type: integer
description: Same as the HTTP status code.
message:
description: >-
Human-readable. A validation failure (400) returns an array of
per-field messages instead of one string.
anyOf:
- type: string
- type: array
items:
type: string
errors:
type: array
description: >-
Present on 400 validation failures: one entry per invalid field. The
flat human-readable strings stay in `message` for back-compat; this
is the machine-readable, per-field view.
items:
type: object
properties:
field:
type: string
description: >-
Name of the invalid field, dot-notated for nested properties
(e.g. `checkoutFields.0.type`).
message:
type: string
description: Validation messages for that field, joined with `, `.
required:
- field
- message
requestId:
type: string
description: >-
Correlation id, identical to the `x-request-id` response header.
Include it when contacting support. On success it is available on
the header only, not the body.
timestamp:
type: string
format: date-time
required:
- statusCode
- message
- timestamp
TransactionMoney:
type: object
description: >-
Render-ready breakdown, computed server-side so you never sum this
yourself. All values integer minor units in money.currency.
properties:
currency:
type: string
description: ISO 4217, upper-case.
grossMinor:
type: integer
description: >-
Your ex-VAT sale base (feeMinor + netMinor). The buyer paid
grossMinor + vatMinor.
feeMinor:
type: integer
description: AgentaOS's commission alone, 0 when none. Never includes VAT.
vatMinor:
type: integer
description: >-
Destination VAT AgentaOS collected and remits as Merchant of Record.
On top of grossMinor, never your revenue.
netMinor:
type: integer
description: What actually reaches your balance (grossMinor - feeMinor).
required:
- currency
- grossMinor
- feeMinor
- vatMinor
- netMinor
examples:
TransactionListExample:
value:
items:
- id: 8c7d6e5f-4a3b-2c1d-0e9f-8a7b6c5d4e3f
payment_link_id: 3f1a2b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c
session_id: mZrESFyR7RC9RPsJfZCVkg
org_id: 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
direction: inbound
payer_address: null
payer_type: human
amount: 49.99
payment_token: EURC
settlement_token: EURC
status: confirmed
tx_hash: null
vendor_reference: pi_3P...
network: stripe
to_address: null
recipient_label: null
description: 'Order #123'
payment_method: card
seller_of_record: aristokrates_ou
invoice_id: b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e
created_at: '2026-08-06T12:05:00.000Z'
environment: live
money:
currency: EUR
grossMinor: 4999
feeMinor: 215
vatMinor: 0
netMinor: 4784
total: 214
hasMore: true
responses:
Unauthorized:
description: Missing or invalid `x-api-key`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
statusCode: 401
message: Invalid API key
timestamp: '2026-08-06T12:00:00.000Z'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your secret key, from app.agentaos.ai -> Settings -> Developers -> API
Keys. The key's prefix is both its identity and its environment:
`sk_test_...` (sandbox, free, no verification) or `sk_live_...` (real
money, requires business verification). A missing or invalid key returns
401.
````