Stellar Claimable Balances API

openapi: 3.2.0
info:
  title: Horizon Claimable Balances API
  version: 0.0.1
  summary: Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by Stellar Core. This API serves the bridge between apps and Stellar Core. Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.
  description: 'Horizon provides an HTTP API to data in the Stellar network. It ingests and re-serves the data produced by the Stellar network in a form that is easier to consume by the average application relative to the performance-oriented data representations used by [Stellar Core](https://developers.stellar.org/network/core-node). This API serves the bridge between apps and Stellar Core. Projects like wallets, decentralized exchanges, and asset issuers use Horizon to submit transactions, query an account balance, or stream events like transactions to an account.


    Horizon can be accessed via cURL, a browser, or one of the [Stellar SDKs](https://developers.stellar.org/docs/tools/sdks). To reduce the complexity of your project, we recommend you use an SDK instead of making direct API calls.


    This guide describes how to administer a production Horizon instance (refer to the [Developers'' Blog](https://www.stellar.org/developers-blog/a-new-sun-on-the-horizon) for some background on the performance and architectural improvements of this major version bump). For information about developing on the Horizon codebase, check out the [Development Guide](https://github.com/stellar/stellar-horizon/blob/main/DEVELOPING.md).


    Before we begin, it''s worth reiterating the sentiment echoed in the [Core Node](https://developers.stellar.org/network/core-node) documentation: **we do not endorse running Horizon backed by a standalone Stellar Core instance**, and especially not by a _validating_ Stellar Core. These are two separate concerns, and decoupling them is important for both reliability and performance. Horizon instead manages its own, pared-down version of Stellar Core optimized for its own subset of needs (we''ll refer to this as a "Captive Core" instance).

    '
  termsOfService: https://stellar.org/terms-of-service
  contact:
    name: Stellar Development Foundation
    url: https://stellar.org
    email: hello@stellar.org
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://horizon-testnet.stellar.org
  description: The Testnet Network
- url: https://horizon-futurenet.stellar.org
  description: The Futurenet network
tags:
- name: Claimable Balances
  description: A Claimable Balance represents the transfer of ownership of some amount of an asset. Claimable balances provide a mechanism for setting up a payment which can be claimed in the future. This allows you to make payments to accounts which are currently not able to accept them.
paths:
  /claimable_balances:
    get:
      tags:
      - Claimable Balances
      summary: List All Claimable Balances
      description: This endpoint lists all available claimable balances.
      operationId: ListAllClaimableBalances
      parameters:
      - $ref: '#/components/parameters/SponsorParam'
      - $ref: '#/components/parameters/AssetParam'
      - $ref: '#/components/parameters/ClaimantParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/OrderParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - $ref: '#/components/schemas/ClaimableBalances'
              examples:
                ListAllClaimableBalances:
                  $ref: '#/components/examples/ListAllClaimableBalances'
  /claimable_balances/{claimable_balance_id}:
    get:
      tags:
      - Claimable Balances
      summary: Retrieve a Claimable Balance
      description: The single claimable balance endpoint provides information on a claimable balance.
      operationId: RetrieveAClaimableBalance
      parameters:
      - $ref: '#/components/parameters/ClaimableBalanceIdParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimableBalance'
              examples:
                RetrieveAClaimableBalance:
                  $ref: '#/components/examples/RetrieveAClaimableBalance'
  /claimable_balances/{claimable_balance_id}/transactions:
    get:
      tags:
      - Claimable Balances
      summary: Retrieve Related Transactions
      description: This endpoint represents successful transactions referencing a given claimable balance and can be used in streaming mode. Streaming mode allows you to listen for new transactions referencing this claimable balance as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known transaction unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream transactions created since your request time.
      operationId: CBRetrieveRelatedTransactions
      parameters:
      - $ref: '#/components/parameters/ClaimableBalanceIdParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/OrderParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/IncludeFailedParam'
      x-supports-streaming: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - $ref: '#/components/schemas/Transaction'
              examples:
                CBRetrieveRelatedTransactions:
                  $ref: '#/components/examples/CBRetrieveRelatedTransactions'
  /claimable_balances/{claimable_balance_id}/operations:
    get:
      tags:
      - Claimable Balances
      summary: Retrieve Related Operations
      description: This endpoint represents successful operations referencing a given claimable balance and can be used in streaming mode. Streaming mode allows you to listen for new operations referencing this claimable balance as they are added to the Stellar ledger. If called in streaming mode, Horizon will start at the earliest known operation unless a cursor is set, in which case it will start from that cursor. By setting the cursor value to now, you can stream operations created since your request time.
      operationId: CBRetrieveRelatedOperations
      parameters:
      - $ref: '#/components/parameters/ClaimableBalanceIdParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/OrderParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/IncludeFailedParam'
      - $ref: '#/components/parameters/JoinParam'
      x-supports-streaming: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - oneOf:
                  - $ref: '#/components/schemas/CreateAccount'
                  - $ref: '#/components/schemas/Payment'
                  - $ref: '#/components/schemas/PathPaymentStrictReceive'
                  - $ref: '#/components/schemas/PathPaymentStrictSend'
                  - $ref: '#/components/schemas/AccountMerge'
              examples:
                CBRetrieveRelatedOperations:
                  $ref: '#/components/examples/CBRetrieveRelatedOperations'
components:
  parameters:
    ClaimantParam:
      name: claimant
      in: query
      required: false
      description: Account ID of the destination address. Only include claimable balances which can be claimed by the given account ID.
    AssetParam:
      name: asset
      in: query
      required: false
      description: An issued asset represented as “Code:IssuerAccountID”. Every account in the response will have a trustline for the given asset.
    OrderParam:
      name: order
      in: query
      required: false
      description: A designation of the order in which records should appear. Options include `asc` (ascending) or `desc` (descending). If this argument isn’t set, it defaults to `asc`.
      schema:
        type: string
        enum:
        - asc
        - desc
    ClaimableBalanceIdParam:
      name: claimable_balance_id
      in: path
      required: true
      description: A unique identifier for this claimable balance.
      schema:
        type: string
    SponsorParam:
      name: sponser
      in: query
      required: false
      description: Account ID of the sponsor. Every account in the response will either be sponsored by the given account ID or have a subentry (trustline, offer, or data entry) which is sponsored by the given account ID.
      schema:
        type: string
        example: GDMQQNJM4UL7QIA66P7R2PZHMQINWZBM77BEBMHLFXD5JEUAHGJ7R4JZ
    IncludeFailedParam:
      name: include_failed
      in: query
      required: false
      description: Set to true to include failed operations in results. Options include true and false.
      schema:
        type: boolean
        enum:
        - true
        - false
    LimitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.
      schema:
        type: integer
        example: 10
    JoinParam:
      name: join
      in: query
      required: false
      description: Set to transactions to include the transactions which created each of the operations in the response.
    CursorParam:
      name: cursor
      in: query
      required: false
      description: A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.
      schema:
        type: integer
        example: 6606617478959105
  schemas:
    AccountMerge:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            transaction:
              $ref: '#/components/schemas/link'
            effects:
              $ref: '#/components/schemas/link'
            succeeds:
              $ref: '#/components/schemas/link'
            precedes:
              $ref: '#/components/schemas/link'
          required:
          - self
          - transaction
          - effects
          - succeeds
          - precedes
        id:
          $ref: '#/components/schemas/id'
        paging_token:
          type: string
        transaction_successful:
          type: boolean
        source_account:
          $ref: '#/components/schemas/address'
        type:
          type: string
          example: account_merge
        type_i:
          type: number
          example: 8
        created_at:
          type: string
        transaction_hash:
          type: string
        account:
          $ref: '#/components/schemas/address'
        into:
          $ref: '#/components/schemas/address'
      required:
      - id
      - paging_token
      - transaction_successful
      - source_account
      - type
      - type_i
      - created_at
      - transaction_hash
      - account
      - into
    PathPaymentStrictSend:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            transaction:
              $ref: '#/components/schemas/link'
            effects:
              $ref: '#/components/schemas/link'
            succeeds:
              $ref: '#/components/schemas/link'
            precedes:
              $ref: '#/components/schemas/link'
          required:
          - self
          - transaction
          - effects
          - succeeds
          - precedes
        id:
          $ref: '#/components/schemas/id'
        paging_token:
          type: string
        transaction_successful:
          type: boolean
        source_account:
          $ref: '#/components/schemas/address'
        type:
          type: string
          example: path_payment_strict_send
        type_i:
          type: number
          example: 13
        created_at:
          type: string
        transaction_hash:
          type: string
        asset_type:
          type: string
          enum:
          - native
          - credit_alphanum4
          - credit_alphanum12
        asset_code:
          type: string
        asset_issuer:
          $ref: '#/components/schemas/address'
        from:
          $ref: '#/components/schemas/address'
        to:
          $ref: '#/components/schemas/address'
        amount:
          type: string
        path:
          type: array
          items:
            type: object
            properties:
              asset_type:
                type: string
                enum:
                - native
                - credit_alphanum4
                - credit_alphanum12
              asset_code:
                type: string
              asset_issuer:
                $ref: '#/components/schemas/address'
        source_amount:
          type: string
        source_max:
          type: string
        source_asset_type:
          type: string
        source_asset_code:
          type: string
        source_asset_issuer:
          $ref: '#/components/schemas/address'
      required:
      - id
      - paging_token
      - transaction_successful
      - source_account
      - type
      - type_i
      - created_at
      - transaction_hash
      - from
      - to
      - amount
      - path
      - source_amount
      - source_asset_type
    ClaimableBalance:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            operations:
              $ref: '#/components/schemas/link'
            transactions:
              $ref: '#/components/schemas/link'
          required:
          - self
          - operations
          - transactions
        id:
          $ref: '#/components/schemas/id'
        asset:
          type: string
        amount:
          type: string
        sponsor:
          type: string
        last_modified_ledger:
          type: string
        last_modified_time:
          type: string
        claimants:
          type: array
          items:
            type: object
            properties:
              destination:
                $ref: '#/components/schemas/address'
              predicate:
                type: object
                properties:
                  and:
                    type: array
                    items:
                      type: object
                      properties:
                        or:
                          type: array
                          items:
                            type: object
                            properties:
                              relBefore:
                                type: string
                              absBefore:
                                type: string
                              absBeforeEpoch:
                                type: string
                        not:
                          type: object
                          properties:
                            unconditional:
                              type: boolean
                            relBefore:
                              type: string
                            absBefore:
                              type: string
                            absBeforeEpoch:
                              type: string
        flags:
          type: integer
        paging_token:
          type: string
      required:
      - id
      - paging_token
      - asset
      - amount
      - last_modified_ledger
      - last_modified_time
    TransactionPreconditionsTimebounds:
      type: object
      properties:
        min_time:
          type: string
        max_time:
          type: string
    PathPaymentStrictReceive:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            transaction:
              $ref: '#/components/schemas/link'
            effects:
              $ref: '#/components/schemas/link'
            succeeds:
              $ref: '#/components/schemas/link'
            precedes:
              $ref: '#/components/schemas/link'
          required:
          - self
          - transaction
          - effects
          - succeeds
          - precedes
        id:
          $ref: '#/components/schemas/id'
        paging_token:
          type: string
        transaction_successful:
          type: boolean
        source_account:
          $ref: '#/components/schemas/address'
        type:
          type: string
          example: path_payment_strict_receive
        type_i:
          type: number
          example: 2
        created_at:
          type: string
        transaction_hash:
          type: string
        asset_type:
          type: string
          enum:
          - native
          - credit_alphanum4
          - credit_alphanum12
        asset_code:
          type: string
        asset_issuer:
          $ref: '#/components/schemas/address'
        from:
          $ref: '#/components/schemas/address'
        to:
          $ref: '#/components/schemas/address'
        amount:
          type: string
        path:
          type: array
          items:
            type: object
            properties:
              asset_type:
                type: string
                enum:
                - native
                - credit_alphanum4
                - credit_alphanum12
              asset_code:
                type: string
              asset_issuer:
                $ref: '#/components/schemas/address'
        source_amount:
          type: string
        destination_min:
          type: string
        source_asset_type:
          type: string
        source_asset_code:
          type: string
        source_asset_issuer:
          $ref: '#/components/schemas/address'
      required:
      - id
      - paging_token
      - transaction_successful
      - source_account
      - type
      - type_i
      - created_at
      - transaction_hash
      - from
      - to
      - amount
      - path
      - source_amount
      - destination_min
    Links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            next:
              $ref: '#/components/schemas/link'
            prev:
              $ref: '#/components/schemas/link'
    FeeBumpTransaction:
      type: object
      properties:
        hash:
          $ref: '#/components/schemas/hash'
        signatures:
          $ref: '#/components/schemas/signatures'
    Transaction:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  memo:
                    type: string
                  _links:
                    type: object
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                      account:
                        $ref: '#/components/schemas/link'
                      ledger:
                        $ref: '#/components/schemas/link'
                      operations:
                        $ref: '#/components/schemas/link'
                      effects:
                        $ref: '#/components/schemas/link'
                      precedes:
                        $ref: '#/components/schemas/link'
                      succeeds:
                        $ref: '#/components/schemas/link'
                      transaction:
                        $ref: '#/components/schemas/link'
                    required:
                    - self
                    - account
                    - ledger
                    - operations
                    - effects
                    - precedes
                    - succeeds
                    - transaction
                  id:
                    $ref: '#/components/schemas/id'
                  paging_token:
                    type: string
                  successful:
                    type: boolean
                  hash:
                    type: string
                  ledger:
                    type: integer
                    format: int32
                  created_at:
                    type: string
                  source_account:
                    $ref: '#/components/schemas/address'
                  account_muxed:
                    type: string
                  account_muxed_id:
                    type: string
                  source_account_sequence:
                    type: string
                  fee_account:
                    $ref: '#/components/schemas/address'
                  fee_account_muxed:
                    $ref: '#/components/schemas/address'
                  fee_account_muxed_id:
                    type: string
                  fee_charged:
                    type: string
                  max_fee:
                    type: string
                  operation_count:
                    type: integer
                    format: int32
                  envelope_xdr:
                    type: string
                  result_xdr:
                    type: string
                  result_meta_xdr:
                    type: string
                  fee_meta_xdr:
                    type: string
                  memo_type:
                    type: string
                  signatures:
                    $ref: '#/components/schemas/signatures'
                  preconditions:
                    $ref: '#/components/schemas/TransactionPreconditions'
                  fee_bump_transaction:
                    $ref: '#/components/schemas/FeeBumpTransaction'
                  inner_transaction:
                    $ref: '#/components/schemas/InnerTransaction'
                required:
                - id
                - paging_token
                - successful
                - hash
                - ledger
                - created_at
                - source_account
                - source_account_sequence
                - fee_account
                - fee_charged
                - max_fee
                - operation_count
                - envelope_xdr
                - result_xdr
                - result_meta_xdr
                - memo_type
                - signatures
    CreateAccount:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            transaction:
              $ref: '#/components/schemas/link'
            effects:
              $ref: '#/components/schemas/link'
            succeeds:
              $ref: '#/components/schemas/link'
            precedes:
              $ref: '#/components/schemas/link'
          required:
          - self
          - transaction
          - effects
          - succeeds
          - precedes
        id:
          $ref: '#/components/schemas/id'
        paging_token:
          type: string
        transaction_successful:
          type: boolean
        source_account:
          $ref: '#/components/schemas/address'
        type:
          type: string
          example: create_account
        type_i:
          type: number
          example: 0
        created_at:
          type: string
        transaction_hash:
          type: string
        starting_balance:
          type: string
        funder:
          $ref: '#/components/schemas/address'
        account:
          $ref: '#/components/schemas/address'
      required:
      - id
      - paging_token
      - transaction_successful
      - source_account
      - type
      - type_i
      - created_at
      - transaction_hash
      - starting_balance
      - funder
      - account
    ClaimableBalances:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                      operations:
                        $ref: '#/components/schemas/link'
                      transactions:
                        $ref: '#/components/schemas/link'
                    required:
                    - self
                    - operations
                    - transactions
                  id:
                    $ref: '#/components/schemas/id'
                  paging_token:
                    type: string
                  asset:
                    type: string
                  amount:
                    type: string
                  sponsor:
                    type: string
                  last_modified_ledger:
                    type: string
                  last_modified_time:
                    type: string
                  claimants:
                    type: array
                    items:
                      type: object
                      properties:
                        destination:
                          $ref: '#/components/schemas/address'
                        predicate:
                          type: object
                          properties:
                            and:
                              type: array
                              items:
                                type: object
                                properties:
                                  or:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        relBefore:
                                          type: string
                                        absBefore:
                                          type: string
                                        absBeforeEpoch:
                                          type: string
                                  not:
                                    type: object
                                    properties:
                                      unconditional:
                                        type: boolean
                                      relBefore:
                                        type: string
                                      absBefore:
                                        type: string
                                      absBeforeEpoch:
                                        type: string
                  flags:
                    type: integer
                required:
                - id
                - paging_token
                - asset
                - amount
                - last_modified_ledger
                - last_modified_time
    hash:
      type: string
    Payment:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                      transaction:
                        $ref: '#/components/schemas/link'
                      effects:
                        $ref: '#/components/schemas/link'
                      succeeds:
                        $ref: '#/components/schemas/link'
                      precedes:
                        $ref: '#/components/schemas/link'
                    required:
                    - self
                    - transaction
                    - effects
                    - succeeds
                    - precedes
                  id:
                    $ref: '#/components/schemas/id'
                  paging_token:
                    type: string
                  transaction_successful:
                    type: boolean
                  source_account:
                    $ref: '#/components/schemas/address'
                  type:
                    type: string
                    example: payment
                  type_i:
                    type: string
                  created_at:
                    type: string
                  transaction_hash:
                    type: string
                  asset_type:
                    type: string
                  asset_code:
                    enum:
                    - native
                    - credit_alphanum4
                    - credit_alphanum12
                  asset_issuer:
                    $ref: '#/components/schemas/address'
                  from:
                    $ref: '#/components/schemas/address'
                  to:
                    $ref: '#/components/schemas/address'
                  amount:
                    type: string
                required:
                - id
                - paging_token
                - transaction_successful
                - source_account
                - type
                - type_i
                - created_at
                - transaction_hash
                - asset_type
                - from
                - to
                - amount
    link:
      type: object
      properties:
        href:
          type: string
          format: link
        templated:
          type: boolean
      required:
      - href
    signatures:
      type: array
      items:
        type: string
        pattern: G[A-Z0-9]{55}
    TransactionPreconditions:
      type: object
      properties:
        timebounds:
          $ref: '#/components/schemas/TransactionPreconditionsTimebounds'
        ledgerbounds:
          $ref: '#/components/schemas/TransactionPreconditionsLedgerbounds'
        min_account_sequence:
          type: string
        min_account_sequence_age:
          type: string
        min_account_sequence_ledger_gap:
          type: integer
          format: uint32
        extra_signers:
          type: array
          items:
            type: string
    InnerTransaction:
      type: object
      properties:
        hash:
          $ref: '#/components/schemas/hash'
        signatures:
          $ref: '#/components/schemas/signatures'
        max_fee:
          type: string
    address:
      type: string
      pattern: G[A-Z0-9]{55}
    TransactionPreconditionsLedgerbounds:
      type: object
      properties:
        min_ledger:
          type: string
        max_ledger:
          type: string
    id:
      type: string
  examples:
    ListAllClaimableBalances:
      value:
        _links:
          self:
            href: https://horizon-testnet.stellar.org/claimable_balances?asset=native&cursor=&limit=10&order=asc
          next:
            href: https://horizon-testnet.stellar.org/claimable_balances?asset=native&cursor=35938300-0000000017b9a95e25aa60200b52cc04f75c496dca76dc19fec21c942dfb35cce23c3eba&limit=10&order=asc
          prev:
            href: https://horizon-testnet.stellar.org/claimable_balances?asset=native&cursor=33324106-00000000691787983bc3ea12361092fe49ae83cbbe37804ee1590fe2b9b3e3860fc8261f&limit=10&order=desc
        _embedded:
          records:
          - _links:
              self:
                href: https://horizon-testnet.stellar.org/claimable_balances/00000000691787983bc3ea12361092fe49ae83cbbe37804ee1590fe2b9b3e3860fc8261f


# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stellar/refs/heads/main/openapi/stellar-claimable-balances-api-openapi.yml