GET /tx-relay/v1/swap/status/:trade-hash

Submit a GET request to /tx-relay/v1/swap/status/:trade-hash to check the status of a trade

Request

Example Request

curl '<https://api.0x.org/tx-relay/v1/swap/status/0xd114c77249bb3a137634afeba1ea1c8d6080c687c1a00cc4137fd9cb905a5fb6>' \\
--header '0x-api-key: <API_KEY>' --header '0x-chain-id: 137'

Response

Example Response

// confirmed
{
    "status": 'confirmed',
    "transactions": [{
        "hash": "0x...",
        "timestamp": 1624290253193
    }]
}

// failed due to transaction reverted
{
    "status": "failed",
    "transactions": [{
        "hash": "0x...",
        "timestamp": 1624290253193
    }],
    "reason": "transaction_reverted"
}

Shape of Response

{
    "transactions": { hash: string; timestamp: number /* unix ms */ }[];
    // For pending, expect no transactions.
    // For successful transactions (i.e. "succeeded"/"confirmed), expect just the mined transaction.
    // For failed transactions, there may be 0 (failed before submission) to multiple transactions (transaction reverted).
    // For submitted transactions, there may be multiple transactions, but only one will ultimately get mined
} & ({ status: 'pending' | 'submitted' | 'succeeded' | 'confirmed' } |
     { status: 'failed'; reason: JobFailureReason });
     // When status field is 'failed', there will be a reason field to describe the error reason

Possible Reasons for Failure

enum JobFailureReason {
    // Transaction simulation failed so no transaction is submitted onchain.
    // Our system simulate the transaction before submitting onchain.
    TransactionSimulationFailed = 'transaction_simulation_failed';
    // The order expired
    OrderExpired = 'order_expired';
    // Last look declined by the market maker
    LastLookDeclined = 'last_look_declined';
    // Transaction(s) submitted onchain but reverted
    TransactionReverted = 'transaction_reverted';
    // Error getting market signature / signature is not valid; this is NOT last look decline
    MarketMakerSignatureError = 'market_maker_sigature_error';
    // Fallback error reason
    InternalError = 'internal_error';
}

Note

JobFailureReason.InternalError is used as the fallback error if the error reason is not one of the errors listed in JobFailureReason.

In the future, 0x might add more entries in JobFailureReasonto provide more information about the failure. Thus, if you were to switch the reason field, it’s recommended to use:

switch (reason) {
    case 'transaction_simulation_failed':
        ...
    case 'order_expired':
        ...
    default:
        // case for internal_error
}

instead of:

switch (reason) {
    case 'transaction_simulation_failed':
        ...
    case 'order_expired':
        ...
    case 'internal_error':
        ...
    default:
        throw
}

to avoid unintended errors.

Status Code

• 200 if successful.
• 404 if the trade hash cannot be found.
• 500 if there is an internal server error.