Get account balances

POST /account/get-balances
Api key auth

Retrieve current balances for specified accounts. Can query single or multiple accounts in one request.

application/json

Body Required

  • data object Required

    The actual request data to be processed

    Hide data attributes Show data attributes object
    • accountIds array[string]

      List of account IDs to query

    • includePending boolean

      Include pending transactions in balance calculation

      Default value is false.

  • signature string Required

    ed25519 signature of the data, signed with user's private key

  • publicKey string Required

    User's derived public key for signature verification

  • timestamp integer Required

    Unix timestamp when the request was created (milliseconds)

  • nonce string Required

    Unique nonce to prevent replay attacks

Responses

  • 200 application/json

    Balances retrieved successfully

    Hide response attributes Show response attributes object
    • success boolean
    • balances array[object]
      Hide balances attributes Show balances attributes object
      • accountId string

        Account identifier

      • balance number

        Current balance

      • availableBalance number

        Available balance

      • pendingBalance number

        Pending transactions

      • currency string

        Currency code

      • lastUpdated string(date-time)

        When balance was last updated

    • timestamp string(date-time)

      When the balances were calculated
  • 400

    Invalid account IDs

  • 401

    Authentication failed

  • 429

    Rate limit exceeded

  • 500

    Internal server error

POST /account/get-balances 
curl \
 --request POST 'https://pay-api.aiic.nz/v1/account/get-balances' \
 --header "X-Public-Key: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"data":{"accountIds":["acc_123","acc_456"],"includePending":false},"signature":"base64-encoded-signature","publicKey":"base64-encoded-public-key","timestamp":1703123456789,"nonce":"abc123-def456-ghi789"}'
Request examples 
{
  "data": {
    "accountIds": [
      "acc_123",
      "acc_456"
    ],
    "includePending": false
  },
  "signature": "base64-encoded-signature",
  "publicKey": "base64-encoded-public-key",
  "timestamp": 1703123456789,
  "nonce": "abc123-def456-ghi789"
}
Response examples (200) 
{
  "success": true,
  "balances": [
    {
      "accountId": "acc_123",
      "balance": 5000,
      "availableBalance": 4500,
      "pendingBalance": 500,
      "currency": "NZD",
      "lastUpdated": "2025-05-04T09:42:00Z"
    }
  ],
  "timestamp": "2025-05-04T09:42:00Z"
}