> ## Documentation Index
> Fetch the complete documentation index at: https://docs.halliday.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get wallet balances

> Retrieve balances for the wallets associated with a payment. You can optionally supply additional
wallet and token pairs to check alongside the payment's primary wallet.




## OpenAPI

````yaml /public/openapi.yaml post /payments/balances
openapi: 3.1.0
info:
  title: Halliday API V2
  description: >
    API V2 for Halliday's payment infrastructure, supporting onramps, swaps, and
    offramps.


    This API provides a unified interface for cryptocurrency payments, allowing
    developers to:

    - Quote payments across multiple providers

    - Execute payments with onramps, swaps, and offramps

    - Track payment status and history


    ## Authentication


    API key authentication is required for all endpoints.
  version: 2.0.0
  contact:
    name: Contact Halliday
    url: https://halliday.xyz
    email: support@halliday.xyz
servers:
  - url: https://v2.prod.halliday.xyz
    description: Base domain
security:
  - ApiKeyAuth: []
tags:
  - name: Chains
    description: Blockchain network information and configuration
  - name: Assets
    description: Asset information, discovery, and supported asset pairs
  - name: Payments
    description: >-
      Core payment operations including quotes, confirmation, and status
      tracking
  - name: Webhooks
    description: >
      Register HTTPS endpoints to receive signed notifications when a workflow
      reaches a terminal

      state, instead of polling for status. You subscribe to one or more event
      types per webhook.


      | Event type | Fires when a workflow's status becomes |

      | --- | --- |

      | `WORKFLOW_COMPLETED` | `COMPLETE` |

      | `WORKFLOW_FAILED` | `FAILED` |


      All management endpoints live under `/orgs/webhooks` and authenticate with
      a secret API key

      (passed as a bearer token) that has webhook access. Publishable keys
      cannot manage webhooks.


      **Integration checklist**


      - Receiver is a public HTTPS endpoint (no private IPs).

      - Save the `signing_secret` when you create the webhook — it is shown only
      once.

      - Verify `X-Halliday-Signature` against the raw body, accepting any of its
      comma-separated signatures.

      - Respond `2xx` quickly and do the real work afterward.

      - Skip deliveries whose `id` you have already handled.
paths:
  /payments/balances:
    post:
      tags:
        - Payments
      summary: Get wallet balances
      description: >
        Retrieve balances for the wallets associated with a payment. You can
        optionally supply additional

        wallet and token pairs to check alongside the payment's primary wallet.
      operationId: getPaymentBalances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestForPaymentBalances'
            example:
              payment_id: pay_abc123
              custom_queries:
                - address: '0xabc1234567890abcdef1234567890abcdef1234'
                  token: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
                - address: '0xdef1234567890abcdef1234567890abcdef5678'
                  token: arbitrum:0xfffFFFFFfFFfffFFfFffffFffFFfFFfFFfFFf
      responses:
        '200':
          description: Wallet balances retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentBalancesResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid wallet address format
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Invalid API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: You do not have permission to query payment balances
        '404':
          description: Payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errors:
                  - kind: other
                    message: Payment 'pay_abc123' not found
components:
  schemas:
    RequestForPaymentBalances:
      type: object
      properties:
        payment_id:
          type: string
          format: uuid
          description: Payment identifier whose associated wallets should be queried.
          example: 41b16a6f-704e-44ba-9964-2b66df8a73e8
        custom_queries:
          type: array
          description: Additional wallet and token combinations to query.
          items:
            type: object
            required:
              - address
              - token
            properties:
              address:
                type: string
                description: Wallet address to query.
                example: '0xabc1234567890abcdef1234567890abcdef1234'
              token:
                $ref: '#/components/schemas/Token'
                description: Token identifier to query at the wallet address.
                example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    PaymentBalancesResponse:
      type: object
      required:
        - balance_results
      properties:
        balance_results:
          type: array
          items:
            $ref: '#/components/schemas/PaymentBalancesResult'
    ErrorResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
      description: Error response for known errors
    Token:
      type: string
      description: Token identifier in the format "chain:address"
      pattern: ^[a-z]+:0x[a-fA-F0-9]+$
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    PaymentBalancesResult:
      type: object
      required:
        - address
        - token
        - account
        - value
      properties:
        address:
          type: string
          description: Wallet address that was queried.
          example: '0xabc1234567890abcdef1234567890abcdef1234'
        token:
          $ref: '#/components/schemas/Token'
          description: Token identifier that was queried.
          example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
        account:
          type: string
          description: Account type for the balance.
          enum:
            - INTENT
            - SPW
        value:
          oneOf:
            - type: object
              required:
                - kind
                - amount
                - withdrawal_fee
              properties:
                kind:
                  type: string
                  enum:
                    - amount
                amount:
                  type: string
                  description: Balance amount as a decimal string.
                withdrawal_fee:
                  type: string
                  nullable: true
                  description: Withdrawal fee amount, or null if not applicable.
            - type: object
              required:
                - kind
              properties:
                kind:
                  type: string
                  enum:
                    - error
          discriminator:
            propertyName: kind
    Issue:
      oneOf:
        - $ref: '#/components/schemas/AmountIssue'
        - $ref: '#/components/schemas/AmountDownstreamIssue'
        - $ref: '#/components/schemas/FundingIssue'
        - $ref: '#/components/schemas/OwnerIssue'
        - $ref: '#/components/schemas/GeolocationIssue'
        - $ref: '#/components/schemas/ProviderIssue'
        - $ref: '#/components/schemas/PayinMethodIssue'
        - $ref: '#/components/schemas/OtherIssue'
        - $ref: '#/components/schemas/UnknownIssue'
      discriminator:
        propertyName: kind
    AmountIssue:
      type: object
      required:
        - kind
        - asset
        - given
        - limits
        - source
        - message
        - reason
      properties:
        kind:
          type: string
          enum:
            - amount
        asset:
          $ref: '#/components/schemas/Asset'
        given:
          $ref: '#/components/schemas/Amount'
        limits:
          $ref: '#/components/schemas/Limits'
        downstream_limits:
          $ref: '#/components/schemas/Limits'
        source:
          type: string
        message:
          type: string
        reason:
          type: string
          enum:
            - TOO_LOW
            - TOO_HIGH
            - NO_VALID_AMOUNT
            - UNKNOWN
    AmountDownstreamIssue:
      type: object
      required:
        - kind
        - asset
        - given
        - limits
        - source
        - message
        - reason
      properties:
        kind:
          type: string
          enum:
            - amount-downstream
        asset:
          $ref: '#/components/schemas/Asset'
        given:
          $ref: '#/components/schemas/Amount'
        limits:
          $ref: '#/components/schemas/Limits'
        downstream_limits:
          $ref: '#/components/schemas/Limits'
        source:
          type: string
        message:
          type: string
        reason:
          type: string
          enum:
            - TOO_LOW
            - TOO_HIGH
            - NO_VALID_AMOUNT
            - UNKNOWN
    FundingIssue:
      type: object
      required:
        - kind
        - token
        - balance
      properties:
        kind:
          type: string
          enum:
            - funding
        token:
          $ref: '#/components/schemas/Token'
        balance:
          type: string
          description: Current token balance at the funding address.
    OwnerIssue:
      type: object
      required:
        - kind
        - message
        - mitigation
      properties:
        kind:
          type: string
          enum:
            - owner
        message:
          type: string
        mitigation:
          type: string
          enum:
            - change
            - verify
    GeolocationIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - geolocation
        message:
          type: string
    ProviderIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - provider
        message:
          type: string
    PayinMethodIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - payin_method
        message:
          type: string
    OtherIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - other
        message:
          type: string
    UnknownIssue:
      type: object
      required:
        - kind
        - message
      properties:
        kind:
          type: string
          enum:
            - unknown
        message:
          type: string
    Asset:
      type: string
      description: >-
        Identifier in the token format ("chain:address") or fiat currency code
        ("USD")
      example: ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
    Amount:
      type: string
      description: A decimal amount string.
    Limits:
      type: object
      properties:
        min:
          type: string
          description: Minimum amount as a decimal string.
        max:
          type: string
          description: Maximum amount as a decimal string.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY

````