Deposits

List incoming activity for your app in one place: invoices (all statuses) and non-invoice on-chain deposits (token_transfers without an invoice_id). Requires authentication (X-App-ID + signature).

Method	Path
`GET`	`/api/v1/deposits`

List Deposits

GET /api/v1/deposits

Returns a combined, paginated list scoped to the authenticated app.

What is included

`type`	Source
`invoice`	Invoice rows for your app (any status)
`non_invoice`	On-chain deposits credited to a listen / deposit wallet that are not linked to an invoice

Query parameters

Param	Type	Default	Description
`type`	string	—	Filter: `invoice` or `non_invoice`
`status`	string	—	Filter: `paid`, `pending`, `failed`, `expired`, or `cancelled`. Alias: `success` is treated as `paid`
`networkId`	string	—	Filter by network UUID
`network`	string	—	Filter by network code (e.g. `polygon-pos`, `ethereum`)
`tokenId`	string	—	Filter by allowed token UUID
`tokenCode`	string	—	Filter by allowed token code (e.g. `usdt-ethereum`)
`walletId`	string	—	Filter by deposit wallet UUID
`q`	string	—	Search across tx hash, invoice id, reference, deposit id, or wallet id
`startDate`	string	—	Inclusive lower bound on `createdAt`. RFC3339 or `YYYY-MM-DD`
`endDate`	string	—	Inclusive upper bound on `createdAt`. RFC3339 or `YYYY-MM-DD` (`YYYY-MM-DD` = end of that UTC day)
`page`	int	`1`	Page number (minimum 1)
`limit`	int	`20`	Page size (minimum 1, maximum 100)

Response `200`

{
  "data": {
    "items": [
      {
        "id": "9544b2ae-c84a-4bc5-a7ed-599b20d0f25d",
        "reference": "order-555",
        "transactionHash": "0x005c514230821be3b7f0a588b9012f76cf1b84a90a28235cf772128ec1775b05",
        "createdAt": "2026-01-15T10:00:00Z",
        "type": "invoice",
        "symbol": "USDT",
        "network": "ethereum",
        "networkId": "net-uuid",
        "tokenId": "tok-uuid",
        "amount": 100,
        "status": "paid",
        "invoiceId": "9544b2ae-c84a-4bc5-a7ed-599b20d0f25d",
        "wallet": {
          "walletId": "wal-uuid",
          "accountId": "acc-uuid",
          "networkId": "net-uuid",
          "network": "ethereum",
          "address": "0x37937c09c7454b1d4ff8fb7657cfd84418168036",
          "addressType": "evm",
          "account": {
            "id": "acc-uuid",
            "appId": "app-uuid",
            "subId": "user-123",
            "mpcSubId": "mpc-sub-id",
            "status": "active",
            "poolType": "organization_owned"
          }
        }
      },
      {
        "id": "44f5465c-e1b4-4128-aa88-728290a9dea6",
        "transactionHash": "0x79ed73ec782a3a01050885b37a7261873369448e6d863be23664f96a40f305fb",
        "createdAt": "2026-01-14T08:30:00Z",
        "type": "non_invoice",
        "symbol": "USDT",
        "network": "ethereum",
        "networkId": "net-uuid",
        "tokenId": "tok-uuid",
        "amount": 25.5,
        "status": "paid",
        "wallet": {
          "walletId": "wal-uuid-2",
          "accountId": "acc-uuid-2",
          "networkId": "net-uuid",
          "network": "ethereum",
          "address": "0xabc...",
          "addressType": "evm"
        }
      }
    ],
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

List envelope

Field	Type	Description
`items`	array	Deposit rows for this page
`total`	number	Total matching rows (before pagination)
`page`	number	Current page
`limit`	number	Page size used

Item fields

Field	Type	Description
`id`	string	Row id (invoice id for `type: invoice`, or token-transfer / deposit id for `non_invoice`)
`reference`	string \| omitted	Your external reference when set (typical for invoices)
`transactionHash`	string	On-chain transaction hash when known; may be empty for unpaid / unpaid-yet invoices
`createdAt`	string (RFC3339)	When the row was created
`type`	string	`invoice` or `non_invoice`
`symbol`	string	Token display symbol (e.g. `USDT`)
`network`	string	Network code (e.g. `ethereum`, `polygon-pos`)
`networkId`	string	Network UUID
`tokenId`	string	Allowed token UUID
`amount`	number	Amount in human-readable token units
`status`	string	Lifecycle status (see below)
`invoiceId`	string \| omitted	Invoice UUID when this row is invoice-related
`wallet`	object \| omitted	Deposit wallet details when available

Status values

Status	Typical meaning
`pending`	Awaiting payment or confirmations
`paid`	Credited / paid (also accepts filter alias `success`)
`failed`	Payment or matching failed
`expired`	Invoice past expiry without payment
`cancelled`	Invoice cancelled

Exact status sets can differ slightly between invoice vs non-invoice rows; use the status and type filters together when you need a narrow slice.

Nested `wallet` object (when present)

Field	Type	Description
`walletId`	string	Deposit wallet UUID
`accountId`	string	Parent account UUID
`networkId`	string	Network UUID
`network`	string	Network code
`address`	string	On-chain deposit address
`addressType`	string	Address family (e.g. `evm`) — may be omitted
`account`	object \| omitted	Parent account summary when loaded

Nested `wallet.account` (when present)

Field	Type	Description
`id`	string	Account UUID
`appId`	string	App UUID
`subId`	string	Your external account identifier
`mpcSubId`	string	MPC-side sub id
`status`	string	Account status (e.g. `active`)
`poolType`	string	`dedicated` or `organization_owned`

Errors

Code	Typical `error`	When
400	`invalid type; use invoice or non_invoice`	Bad `type`
400	`invalid status; use paid, pending, failed, expired, or cancelled`	Bad `status`
400	`invalid startDate; use RFC3339 or YYYY-MM-DD`	Bad `startDate`
400	`invalid endDate; use RFC3339 or YYYY-MM-DD`	Bad `endDate`
400	`startDate must not be after endDate`	Date range inverted

Invoice Withdraw