LedgerReadService

List Transfers

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

Method

GET

Path

/v1/transfers

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

GET

/v1/transfers

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/transfers?ledger=1&limit=100&reversed=false&subaccountId=45LUmqjT' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "transfers": [
    {
      "account": "FUNDING",
      "amount": "18.446744073709551617",
      "asset": "USDT",
      "balanceAfter": "18.446744073709551617",
      "destination": {
        "accountId": "4Rh4iXdT",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
      "isDebit": false,
      "linkId": "1",
      "source": {
        "accountId": "4Rh4iXdT",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "timestamp": "1",
      "transferCode": "DEPOSIT",
      "transferId": "9155001234569"
    }
  ]
}

ledger integer (int32)

Optional public asset filter.

limit integer ≤ 1000

Maximum rows to return (default 100, max 1000).

pageToken string max 512 chars

Opaque keyset cursor returned by the previous response.

reversed boolean

true=newest first; false=oldest first.

subaccountId string /^[1-9A…m-z]+$/

Optional subaccount public id (base58).

timestampMax integer (int64)

Optional inclusive upper transfer time bound in microseconds since Unix epoch (UTC); at least timestampMin when both are set.

timestampMin integer (int64)

Optional inclusive lower transfer time bound in microseconds since Unix epoch (UTC).

nextPageToken string

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

Example eyJvZmZzZXQiOjIwMH0

12 fields

account string

Account bucket affected by this transfer.

Example FUNDING

amount string /^[0-9]…9]+)?$/

Transfer amount at fixed 18-decimal ledger scale.

Example 18.446744073709551617

asset string

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.

Example USDT

balanceAfter string /^[0-9]…9]+)?$/

Post-transfer balance at fixed 18-decimal ledger scale.

Example 18.446744073709551617

4 fields

flowId string

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

Example flow_7YWHMfk9JZeLMgZauHuiSxhJ

isDebit boolean

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

Example false

linkId string /^[0-9]+$/

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

Example 1

4 fields

timestamp string /^[0-9]+$/

Transfer timestamp in microseconds since epoch (UTC).

Example 1

transferCode string

Product reason for this transfer.

Example DEPOSIT

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.

Example 9155001234569

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

GET

/v1/transfers

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/transfers?ledger=1&limit=100&reversed=false&subaccountId=45LUmqjT' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "nextPageToken": "eyJvZmZzZXQiOjIwMH0",
  "transfers": [
    {
      "account": "FUNDING",
      "amount": "18.446744073709551617",
      "asset": "USDT",
      "balanceAfter": "18.446744073709551617",
      "destination": {
        "accountId": "4Rh4iXdT",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "flowId": "flow_7YWHMfk9JZeLMgZauHuiSxhJ",
      "isDebit": false,
      "linkId": "1",
      "source": {
        "accountId": "4Rh4iXdT",
        "address": "0x3333333333333333333333333333333333333333",
        "chainId": 1,
        "kind": "FUNDING_ACCOUNT"
      },
      "timestamp": "1",
      "transferCode": "DEPOSIT",
      "transferId": "9155001234569"
    }
  ]
}