Submit a Transaction Asynchronously

POST 
/transactions_async

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 to wait for the transaction to be included in a ledger and ingested by Horizon.

Request

Query Parameters

tx stringrequired

Responses

201

Transaction has been received by core and is in pending status.

application/json

Schema

Schema

errorResultXdr stringnullable

TransactionResult XDR string which is present only if the submission status from core is an ERROR.

tx_status string

Possible values: [ERROR, PENDING, DUPLICATE, TRY_AGAIN_LATER]

Status of the transaction submission.

hash string

Hash of the transaction.

Example (from schema)

{
  "errorResultXdr": "string",
  "tx_status": "ERROR",
  "hash": "string"
}

TransactionPending

{
  "tx_status": "PENDING",
  "hash": "6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165"
}

400

Transaction is malformed; ERROR status from core.

application/json

Schema

Schema

oneOf

AsyncTransactionSubmissionResponse

errorResultXdr stringnullable

TransactionResult XDR string which is present only if the submission status from core is an ERROR.

tx_status string

Possible values: [ERROR, PENDING, DUPLICATE, TRY_AGAIN_LATER]

Status of the transaction submission.

hash string

Hash of the transaction.

Problem

type string

Identifies the problem type.

title string

A short, human-readable summary of the problem type.

status integer

The HTTP status code for this occurrence of the problem.

detail string

A human-readable explanation specific to this occurrence of the problem.

extras

object

Additional details that might help the client understand the error(s) that occurred.

property name* any

Additional details that might help the client understand the error(s) that occurred.

Example (from schema)

{}

TransactionMalformed

{
  "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

{
  "errorResultXdr": "AAAAAAAAAGT////7AAAAAA==",
  "tx_status": "ERROR",
  "hash": "6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165"
}

403

Transaction submission has been disabled for Horizon.

application/json

Schema

Schema

type string

Identifies the problem type.

title string

A short, human-readable summary of the problem type.

status integer

The HTTP status code for this occurrence of the problem.

detail string

A human-readable explanation specific to this occurrence of the problem.

extras

object

Additional details that might help the client understand the error(s) that occurred.

property name* any

Additional details that might help the client understand the error(s) that occurred.

Example (from schema)

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "extras": {}
}

TransactionSubmissionDisabled

{
  "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

Transaction is a duplicate of a previously submitted transaction.

application/json

Schema

Schema

errorResultXdr stringnullable

TransactionResult XDR string which is present only if the submission status from core is an ERROR.

tx_status string

Possible values: [ERROR, PENDING, DUPLICATE, TRY_AGAIN_LATER]

Status of the transaction submission.

hash string

Hash of the transaction.

Example (from schema)

{
  "errorResultXdr": "string",
  "tx_status": "ERROR",
  "hash": "string"
}

TransactionDuplicate

{
  "tx_status": "DUPLICATE",
  "hash": "6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165"
}

500

Transaction submission failure, exception or invalid status from core.

application/json

Schema

Schema

type string

Identifies the problem type.

title string

A short, human-readable summary of the problem type.

status integer

The HTTP status code for this occurrence of the problem.

detail string

A human-readable explanation specific to this occurrence of the problem.

extras

object

Additional details that might help the client understand the error(s) that occurred.

property name* any

Additional details that might help the client understand the error(s) that occurred.

Example (from schema)

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "extras": {}
}

TransactionFailed

{
  "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

{
  "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

{
  "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

History DB is stale; core is unavailable for transaction submission.

application/json

Schema

Schema

oneOf

AsyncTransactionSubmissionResponse

errorResultXdr stringnullable

TransactionResult XDR string which is present only if the submission status from core is an ERROR.

tx_status string

Possible values: [ERROR, PENDING, DUPLICATE, TRY_AGAIN_LATER]

Status of the transaction submission.

hash string

Hash of the transaction.

Problem

type string

Identifies the problem type.

title string

A short, human-readable summary of the problem type.

status integer

The HTTP status code for this occurrence of the problem.

detail string

A human-readable explanation specific to this occurrence of the problem.

extras

object

Additional details that might help the client understand the error(s) that occurred.

property name* any

Additional details that might help the client understand the error(s) that occurred.

Example (from schema)

{}

HistoryDBStale

{
  "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

{
  "tx_status": "TRY_AGAIN_LATER",
  "hash": "6cbb7f714bd08cea7c30cab7818a35c510cbbfc0a6aa06172a1e94146ecf0165"
}

Loading...