ledger.read.v1.LedgerReadService

ListTransfers

List finalized transfer history for an account. Supports optional subaccount, asset, inclusive time-bound, ordering, and cursor filters.

Method

POST

Path

ledger.read.v1.LedgerReadService/ListTransfers

Service

ledger.read.v1.LedgerReadService

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

POST

ledger.read.v1.LedgerReadService/ListTransfers

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/ledger.read.v1.LedgerReadService/ListTransfers' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "ledger": 1,
  "limit": 100,
  "pageToken": "eyJvZmZzZXQiOjEwMH0",
  "reversed": false,
  "subaccountId": "6789012345678",
  "transferCode": "DEPOSIT",
  "tsMaxUs": "1",
  "tsMinUs": "1"
}'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "transfers": [
    {
      "accountCode": "FUNDING",
      "amountE18": {
        "hi": "1",
        "lo": "1"
      },
      "assetId": 100,
      "balanceAfterE18": {
        "hi": "1",
        "lo": "1"
      },
      "destination": {
        "accountId": "7563897446546",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
      "isDebit": false,
      "linkId": "1",
      "source": {
        "accountId": "7563897446546",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "transferCode": "DEPOSIT",
      "transferId": "9155001234569",
      "tsUs": "1"
    }
  ]
}

Request

ledger.read.v1.ListTransfersRequest

Response

ledger.read.v1.ListTransfersResponse

subaccountId string (fixed64)

Optional public subaccount ID. When omitted, subaccount-scoped API keys use their bound subaccount; other callers use their authenticated root account.

limit integer (int32) ≤ 1000

Maximum number of transfer rows to return. Defaults to 100 when omitted; maximum is 1000.

reversed boolean

Sort direction. When true, rows are returned newest first; when false, rows are returned oldest first.

tsMinUs string (uint64)

Optional lower transfer timestamp bound in microseconds since epoch (UTC), inclusive.

tsMaxUs string (uint64)

Optional upper transfer timestamp bound in microseconds since epoch (UTC), inclusive.

transferCode enum must be defined value

Optional filter by transfer reason.

ledger integer (int32)

Optional filter by asset ledger.

pageToken string max 512 chars

Opaque keyset cursor from a previous response. The cursor is exclusive and bound to the authenticated account, sub-account scope, filters, timestamp bounds, and sort direction.

12 fields

assetId integer (int32)

Public unified asset ID. Resolve its symbol through the spot configuration API. U128 amounts in this row always use a fixed 18-decimal ledger scale.

2 fields

transferCode enum

Product reason for this transfer.

DEPOSIT WITHDRAW MAKER_FEE TAKER_FEE INTERNAL_TRANSFER TRADE_BASE TRADE_QUOTE REBATE FUNDING_TO_TRADING TRADING_TO_FUNDING TRADING_WITHDRAW_RESERVE FUNDING_USER_TRANSFER TRADING_WITHDRAW_REQUEST_FEE

accountCode enum

Account bucket affected by this transfer.

FUNDING TRADING

tsUs string (uint64)

Transfer timestamp in microseconds since epoch (UTC).

2 fields

isDebit boolean

True when this row is the debit leg; false when it is the credit leg.

linkId string (uint64)

Correlation ID used to group related transfer legs. Zero when unavailable.

flowId string

Public lifecycle flow ID when this transfer belongs to a chain lifecycle flow.

4 fields

transferId string

Stable transfer identifier, an unsigned 128-bit integer as a decimal string. Both legs of a transfer share it; with account_code and is_debit it identifies this row.

nextPageToken string max 512 chars

Opaque cursor for the next page. Empty when no more results exist.

Possible errors: 30

Key	HTTP status	Connect code	Error	When
api-key-action-deny	403	permission_denied	API Key Policy Denied	API key policy does not allow this read action.
api-key-policy-not-found	403	permission_denied	API Key Policy Not Found	API key policy was not found.
api-key-policy-required	403	permission_denied	API Key Policy Required	API key policy is required for ledger reads.
api-key-root-scope-only	403	permission_denied	API Key Root Scope Only	This API key is scoped to the root account and cannot read sub-accounts.
api-key-subaccount-mismatch	403	permission_denied	API Key Sub-account Mismatch	This API key is bound to a different sub-account.
api-key-unknown	403	permission_denied	API Key Unknown	The authenticated API key has no metadata entry in the API key store.
auth-authentication-required	401	unauthenticated	Authentication Required	Authentication is required.
auth-session-kind-not-allowed	403	permission_denied	Interactive Session Required	This read accepts only an interactive session; API keys are refused.
bad-request	400	invalid_argument	Bad Request	—
invalid-account-id	400	invalid_argument	Invalid Account ID	—
invalid-argument	400	invalid_argument	Bad Request	—
invalid-subaccount-id	400	invalid_argument	Invalid Sub-account ID	—
ip-not-allowed	401	unauthenticated	API Key IP Not Allowed	API key is not authorized from this IP address.
key-disabled	401	unauthenticated	API Key Disabled	API key is disabled.
key-expired	401	unauthenticated	API Key Expired	API key has expired.
missing-account-id	400	invalid_argument	Missing Account ID	—
missing-headers	400	invalid_argument	Missing API Key Headers	Missing required API key authentication headers.
missing-wallet	400	invalid_argument	Missing Wallet	—
not-found	404	not_found	Not Found	—
permission-denied	403	permission_denied	Permission Denied	—
role-action-deny	403	permission_denied	Role Denied	Your role does not allow this read action.
server-error	500	internal	Server Error	—
signature-invalid	401	unauthenticated	Invalid API Key Signature	API key signature is invalid.
subaccount-policy-deny	403	permission_denied	Sub-account Policy Denied	Sub-account policy does not allow this read action.
subaccount-read-forbidden	403	permission_denied	Sub-account Read Forbidden	You do not have permission to read this sub-account.
timestamp-skew	400	invalid_argument	API Key Timestamp Skew	API key timestamp is outside the allowed skew window.
unauthenticated	401	unauthenticated	Unauthenticated	Ledger reads require a valid bearer JWT or signed API-key request.
upstream-error	502	unavailable	Upstream Error	—
wallet-not-found	404	not_found	Wallet Not Found	—
wallet-resolution-unavailable	502	unavailable	Wallet Resolution Unavailable	—

POST

ledger.read.v1.LedgerReadService/ListTransfers

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/ledger.read.v1.LedgerReadService/ListTransfers' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "ledger": 1,
  "limit": 100,
  "pageToken": "eyJvZmZzZXQiOjEwMH0",
  "reversed": false,
  "subaccountId": "6789012345678",
  "transferCode": "DEPOSIT",
  "tsMaxUs": "1",
  "tsMinUs": "1"
}'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "transfers": [
    {
      "accountCode": "FUNDING",
      "amountE18": {
        "hi": "1",
        "lo": "1"
      },
      "assetId": 100,
      "balanceAfterE18": {
        "hi": "1",
        "lo": "1"
      },
      "destination": {
        "accountId": "7563897446546",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
      "isDebit": false,
      "linkId": "1",
      "source": {
        "accountId": "7563897446546",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "transferCode": "DEPOSIT",
      "transferId": "9155001234569",
      "tsUs": "1"
    }
  ]
}