Stellar Transactions API

openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server Accounts Transactions API
  description: 'The platform server is an internal component. It should be hosted in a private network and should not be accessible from the Internet. This server enables the business to fetch and update the state of transactions using its API.

    '
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://platform-server.exampleanchor.com
tags:
- name: Transactions
  description: Transactions initiated by client applications via SEP APIs
paths:
  /transactions:
    get:
      tags:
      - Transactions
      x-seps:
      - SEP-6
      - SEP-24
      - SEP-31
      summary: Retrieve a List of Transactions
      operationId: getTransactions
      description: Allows to query list of transactions for desired SEP. This api supports pagination, and it's possible (and recommended) to make multiple requests to query transactions. The last page is reached when the number of elements returned by the endpoint is smaller than provided `page_size`.
      parameters:
      - in: query
        name: sep
        required: true
        schema:
          type: string
          enum:
          - '6'
          - '24'
          - '31'
        description: Lookup transactions belonging to this SEP.
      - in: query
        name: order_by
        schema:
          type: string
          enum:
          - created_at
          - transfer_received_at
          - user_action_required_by
          default: created_at
        description: 'Specifies field that transactions will be ordered by. Note, that secondary sort is transaction id in ascending value.

          I.e. when timestamps for 2 or more transactions is identical, they will be sorted by id.'
      - in: query
        name: order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        description: 'Specifies order. Note, that when the field is null, all transactions with null value will be last, regardless of soring order (NULLS LAST).

          For example, transfer time may not be specified for some transactions, resulting into `transfer_received_at` being null. If so, transactions with non-null values will be sorted and returned first, followed by all transactions with null timestamps.'
      - in: query
        name: statuses
        schema:
          type: array
          items:
            $ref: '#/components/schemas/StatusSEPAll'
        description: Filters transactions for specified array of statuses. If not provided, filtering is disabled (default behavior)
      - in: query
        name: page_size
        schema:
          type: integer
          default: 20
        description: Size of a single search page. Must be positive.
      - in: query
        name: page_number
        schema:
          type: integer
          default: 0
        description: Page number to use for continuous search. Page count beings at 0.
      responses:
        '200':
          description: Transaction found.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TransactionListSEP6'
                - $ref: '#/components/schemas/TransactionListSEP24'
                - $ref: '#/components/schemas/TransactionListSEP31'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Transactions
      summary: Submit a Transaction
      description: 'This endpoint actually submits a transaction to the Stellar network. It only takes a single, required parameter: the signed transaction. Refer to the Transactions page for details on how to craft a proper one. If you submit a transaction that has already been included in a ledger, this endpoint will return the same response as would’ve been returned for the original transaction submission. This allows for safe resubmission of transactions in error scenarios, as highlighted in the error-handling guide.'
      operationId: SubmitATransaction
      parameters:
      - in: query
        name: tx
        schema:
          type: string
          description: The base64-encoded XDR of the transaction.
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitTransaction'
              examples:
                SubmitaTransaction:
                  $ref: '#/components/examples/SubmitaTransaction'
  /transactions/{id}:
    get:
      tags:
      - Transactions
      x-seps:
      - SEP-6
      - SEP-24
      - SEP-31
      summary: Retrieve a Transaction
      operationId: getTransaction
      description: Provides the information necessary for the business to determine the state of the transaction identified by `id`, decide if any action must be taken to continue processing the transaction, and act on the decision.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Transaction found.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/TransactionSEP6'
                - $ref: '#/components/schemas/TransactionSEP24'
                - $ref: '#/components/schemas/TransactionSEP31'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Transaction not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transactions/{transaction_hash}:
    get:
      tags:
      - Transactions
      summary: Retrieve a Transaction
      description: The single transaction endpoint provides information on a specific transaction.
      operationId: RetrieveATransaction
      parameters:
      - $ref: '#/components/parameters/HashParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas-Transaction'
              examples:
                RetrieveATransaction:
                  $ref: '#/components/examples/RetrieveATransaction'
  /transactions/{transaction_hash}/operations:
    get:
      tags:
      - Transactions
      summary: Retrieve a Transaction's Operations
      description: This endpoint returns Successful operations for a specific transaction.
      operationId: RetrieveATransactionsOperations
      parameters:
      - $ref: '#/components/parameters/HashParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/OrderParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/IncludeFailedParam'
      - $ref: '#/components/parameters/JoinParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - $ref: '#/components/schemas/Operation'
              examples:
                RetrieveATransactionsOperations:
                  $ref: '#/components/examples/RetrieveATransactionsOperations'
  /transactions/{transaction_hash}/effects:
    get:
      tags:
      - Transactions
      summary: Retrieve a Transaction's Effects
      description: This endpoint returns the effects of a specific transaction.
      operationId: RetrieveATransactionsEffects
      parameters:
      - $ref: '#/components/parameters/HashParam'
      - $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/Effect'
              examples:
                RetrieveATransactionsEffects:
                  $ref: '#/components/examples/RetrieveATransactionsEffects'
  /transactions_async:
    post:
      summary: Submit a Transaction Asynchronously
      description: This endpoint submits transactions to the Stellar network asynchronously. It is designed to allow users to submit transactions without blocking them while waiting for a response from Horizon. At the same time, it also provides clear response status codes from stellar-core to help understand the status of the submitted transaction. You can then use Horizon's [GET transaction endpoint](https://developers.stellar.org/docs/data/apis/horizon/api-reference/resources/retrieve-a-transaction) to wait for the transaction to be included in a ledger and ingested by Horizon.
      operationId: SubmitAsyncTransaction
      tags:
      - Transactions
      parameters:
      - in: query
        name: tx
        schema:
          type: string
          description: The base64-encoded XDR of the transaction.
        required: true
      responses:
        '201':
          description: Transaction has been received by core and is in pending status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTransactionSubmissionResponse'
              examples:
                TransactionPending:
                  summary: Transaction Pending
                  value:
                    tx_status: PENDING
                    hash: 6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165
        '400':
          description: Transaction is malformed; ERROR status from core.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AsyncTransactionSubmissionResponse'
                - $ref: '#/components/schemas/Problem'
              examples:
                TransactionMalformed:
                  summary: Transaction Malformed
                  value:
                    type: transaction_malformed
                    title: Transaction Malformed
                    status: 400
                    detail: Horizon could not decode the transaction envelope in this request. A transaction should be an XDR TransactionEnvelope struct encoded using base64. The envelope read from this request is echoed in the `extras.envelope_xdr` field of this response for your convenience.
                    extras:
                      envelope_xdr: ''
                TransactionError:
                  summary: ERROR Status from core
                  value:
                    error_result_xdr: AAAAAAAAAGT////7AAAAAA==
                    tx_status: ERROR
                    hash: 6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165
        '403':
          description: Transaction submission has been disabled for Horizon.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                TransactionSubmissionDisabled:
                  summary: Transaction Submission Disabled
                  value:
                    type: transaction_submission_disabled
                    title: Transaction Submission Disabled
                    status: 403
                    detail: Transaction submission has been disabled for Horizon. To enable it again, remove env variable DISABLE_TX_SUB.
                    extras:
                      envelope_xdr: ''
        '409':
          description: Transaction is a duplicate of a previously submitted transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTransactionSubmissionResponse'
              examples:
                TransactionDuplicate:
                  summary: Transaction Duplicate
                  value:
                    tx_status: DUPLICATE
                    hash: 6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165
        '500':
          description: Transaction submission failure, exception or invalid status from core.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                TransactionFailed:
                  summary: Transaction Submission Failed
                  value:
                    type: transaction_submission_failed
                    title: Transaction Submission Failed
                    status: 500
                    detail: 'Could not submit transaction to stellar-core. The `extras.error` field on this response contains further details. Descriptions of each code can be found at: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/transaction-submission-async/transaction_submission_failed'
                    extras:
                      envelope_xdr: ''
                      error: Error details here
                TransactionException:
                  summary: Transaction Submission Exception
                  value:
                    type: transaction_submission_exception
                    title: Transaction Submission Exception
                    status: 500
                    detail: 'Received exception from stellar-core. The `extras.error` field on this response contains further details. Descriptions of each code can be found at: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/transaction-submission-async/transaction_submission_exception'
                    extras:
                      envelope_xdr: ''
                      error: Exception details here
                TransactionInvalidStatus:
                  summary: Transaction Submission Invalid Status
                  value:
                    type: transaction_submission_invalid_status
                    title: Transaction Submission Invalid Status
                    status: 500
                    detail: 'Received invalid status from stellar-core. The `extras.error` field on this response contains further details.  Descriptions of each code can be found at: https://developers.stellar.org/api/errors/http-status-codes/horizon-specific/transaction-submission-async/transaction_submission_invalid_status'
                    extras:
                      envelope_xdr: ''
                      error: Error details here
        '503':
          description: History DB is stale; core is unavailable for transaction submission.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AsyncTransactionSubmissionResponse'
                - $ref: '#/components/schemas/Problem'
              examples:
                HistoryDBStale:
                  summary: Historical DB Is Too Stale
                  value:
                    type: stale_history
                    title: Historical DB Is Too Stale
                    status: 503
                    detail: This horizon instance is configured to reject client requests when it can determine that the history database is lagging too far behind the connected instance of Stellar-Core or read replica. It's also possible that Stellar-Core is out of sync. Please try again later.
                    extras:
                      envelope_xdr: ''
                TransactionTryAgainLater:
                  summary: TRY_AGAIN_LATER Status from core
                  value:
                    tx_status: TRY_AGAIN_LATER
                    hash: 6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165
components:
  schemas:
    id:
      type: string
    FeeDetails:
      type: object
      required:
      - total
      - asset
      properties:
        total:
          type: string
        asset:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/FeeDescription'
    StatusSEPAll:
      type: string
      description: Possible status values for all transactions
      enum:
      - incomplete
      - completed
      - refunded
      - expired
      - error
      - pending_stellar
      - pending_external
      - pending_user_transfer_start
      - pending_user_transfer_complete
      - pending_anchor
      - pending_trust
      - pending_user
      - no_market
      - too_small
      - too_large
      - pending_sender
      - pending_receiver
      - pending_transaction_info_update
      - pending_customer_info_update
    paging_token:
      type: string
    TransactionListSEP31:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/TransactionSEP31'
    Error:
      type: object
      properties:
        error:
          type: string
        id:
          type: string
      required:
      - error
    Refunds:
      type: object
      properties:
        amount_refunded:
          $ref: '#/components/schemas/Amount'
        amount_fee:
          $ref: '#/components/schemas/Amount'
        payments:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              id_type:
                type: string
                enum:
                - stellar
                - external
              amount:
                $ref: '#/components/schemas/Amount'
              fee:
                $ref: '#/components/schemas/Amount'
              requested_at:
                type: string
                format: date-time
              refunded_at:
                type: string
                format: date-time
    MemoType:
      type: string
      description: The memo type of the transaction in the Stellar network. Should be present if memo is not null.
      enum:
      - text id hash
    Links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            next:
              $ref: '#/components/schemas/link'
            prev:
              $ref: '#/components/schemas/link'
    Operation:
      type: object
      properties:
        _links:
          type: object
          properties:
            effects:
              $ref: '#/components/schemas/link'
            precedes:
              $ref: '#/components/schemas/link'
            self:
              $ref: '#/components/schemas/link'
            succeds:
              $ref: '#/components/schemas/link'
            transaction:
              $ref: '#/components/schemas/link'
        id:
          $ref: '#/components/schemas/id'
        paging_token:
          $ref: '#/components/schemas/paging_token'
        type_i:
          type: number
          example: 0
        type:
          type: string
          example: create_account
    StatusSEP24:
      type: string
      description: Possible status value for SEP-24 transactions
      enum:
      - incomplete
      - completed
      - refunded
      - expired
      - error
      - pending_stellar
      - pending_external
      - pending_user_transfer_start
      - pending_user_transfer_complete
      - pending_anchor
      - pending_trust
      - pending_user
      - no_market
      - too_small
      - too_large
    InnerTransaction:
      type: object
      properties:
        hash:
          $ref: '#/components/schemas/hash'
        signatures:
          $ref: '#/components/schemas/signatures'
        max_fee:
          type: string
    Amount:
      type: object
      required:
      - amount
      - asset
      properties:
        amount:
          type: string
        asset:
          type: string
    FeeDescription:
      type: object
      required:
      - name
      - amount
      properties:
        name:
          type: string
        amount:
          type: string
        description:
          type: string
    StellarId:
      type: object
      description: 'StellarId''s are objects that identify end-users and SEP-31 Sending Anchors, but not SEP-31 Receiving Anchors.


        For a SEP-12 customer, the `id` field should be sufficient to fully identify the customer in the business'' Backend.


        For a SEP-31 Sending Anchor, the `account` and `memo` fields should be used.


        For a SEP-6 or SEP-24 Anchor, the `account` and `memo` fields should be used.

        '
      properties:
        id:
          type: string
          description: The `id` of the customer registered through SEP-12.
        account:
          type: string
          description: Either the Stellar account or Muxed account address of the on-chain entity.
        memo:
          type: string
          description: The memo value identifying a customer with a shared account, where the shared account is `account`.
    TransactionSEP31:
      type: object
      required:
      - id
      - sep
      - kind
      - status
      - started_at
      properties:
        id:
          type: string
        sep:
          type: string
          enum:
          - '31'
        kind:
          type: string
          enum:
          - receive
        status:
          $ref: '#/components/schemas/StatusSEP31'
        type:
          type: string
          description: This field is always empty for SEP-31 transactions.
        amount_expected:
          $ref: '#/components/schemas/Amount'
        amount_in:
          $ref: '#/components/schemas/Amount'
        amount_out:
          $ref: '#/components/schemas/Amount'
        fee_details:
          $ref: '#/components/schemas/FeeDetails'
        quote_id:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        transfer_received_at:
          type: string
          format: date-time
        user_action_required_by:
          type: string
          format: date-time
        message:
          type: string
        refunds:
          $ref: '#/components/schemas/Refunds'
        stellar_transactions:
          type: array
          items:
            $ref: '#/components/schemas/StellarTransaction'
        source_account:
          type: string
        destination_account:
          type: string
        external_transaction_id:
          type: string
        memo:
          type: string
        memo_type:
          $ref: '#/components/schemas/MemoType'
        refund_memo:
          description: if provided, this memo should be used for refund transactions.
          type: string
        refund_memo_type:
          $ref: '#/components/schemas/MemoType'
        client_domain:
          type: string
        client_name:
          type: string
        customers:
          type: object
          description: 'The Identification info of the sending and receiving customers. If they were created through [SEP-12](https://stellar.org/protocol/sep-12),

            this object should contain the SEP-12 customer `id`. Otherwise, the `account` address of the customer.

            '
          properties:
            sender:
              $ref: '#/components/schemas/StellarId'
            receiver:
              $ref: '#/components/schemas/StellarId'
        creator:
          $ref: '#/components/schemas/StellarId'
    StatusSEP31:
      type: string
      description: Possible status value for SEP-31 transactions
      enum:
      - incomplete
      - completed
      - refunded
      - expired
      - error
      - pending_stellar
      - pending_external
      - pending_sender
      - pending_receiver
      - pending_transaction_info_update
      - pending_customer_info_update
    TransactionSEP6:
      type: object
      required:
      - id
      - sep
      - kind
      - status
      - started_at
      properties:
        id:
          type: string
        sep:
          type: string
          enum:
          - '6'
        kind:
          type: string
          enum:
          - deposit
          - deposit-exchange
          - withdrawal
          - withdrawal-exchange
        status:
          $ref: '#/components/schemas/StatusSEP6'
        type:
          type: string
          description: The method the user used to deposit or withdraw offchain funds.
        amount_expected:
          $ref: '#/components/schemas/Amount'
        amount_in:
          $ref: '#/components/schemas/Amount'
        amount_out:
          $ref: '#/components/schemas/Amount'
        fee_details:
          $ref: '#/components/schemas/FeeDetails'
        quote_id:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        transfer_received_at:
          type: string
          format: date-time
        user_action_required_by:
          type: string
          format: date-time
        message:
          type: string
        refunds:
          $ref: '#/components/schemas/Refunds'
        stellar_transactions:
          type: array
          items:
            $ref: '#/components/schemas/StellarTransaction'
        source_account:
          type: string
        destination_account:
          type: string
        external_transaction_id:
          type: string
        memo:
          type: string
        memo_type:
          $ref: '#/components/schemas/MemoType'
        refund_memo:
          type: string
          description: If provided, this memo should be used for refund transactions.
        refund_memo_type:
          $ref: '#/components/schemas/MemoType'
        client_domain:
          type: string
        client_name:
          type: string
        customers:
          type: object
          description: 'The user that initiated the transaction is both the sender and receiver.

            '
          properties:
            sender:
              $ref: '#/components/schemas/StellarId'
            receiver:
              $ref: '#/components/schemas/StellarId'
        creator:
          $ref: '#/components/schemas/StellarId'
    hash:
      type: string
    SubmitTransaction:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  memo:
                    type: string
                  memo_bytes:
                    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
    signatures:
      type: array
      items:
        type: string
        pattern: G[A-Z0-9]{55}
    TransactionListSEP6:
      type: object
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/TransactionSEP6'
    AsyncTransactionSubmissionResponse:
      type: object
      properties:
        error_result_xdr:
          type: string
          nullable: true
          description: TransactionResult XDR string which is present only if the submission status from core is an ERROR.
        tx_status:
          type: string
          enum:
          - ERROR
          - PENDING
          - DUPLICATE
          - TRY_AGAIN_LATER
          description: Status of the transaction submission.
        hash:
          type: string
          description: Hash of the transaction.
    schemas-Transaction:
      type: object
      properties:
        _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'
          required:
          - self
          - account
          - ledger
          - operations
          - effects
          - precedes
          - succeeds
        id:
          $ref: '#/components/schemas/id'
        paging_token:
          type: string
        successful:
          type: boolean
        hash:
          type: string
        ledger:
          type: integer
          format: int32
        created_at:
          t

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