POST /receipt

POST https://api.trustware.io/api/v1/route-intent/:intentId/receipt After you broadcast the source transaction, commit it to its intent with this call. Trustware tracks the route from the commit through to final settlement. Commit soon after broadcast. Retries are safe, and a commit that arrives late still works. See committing late.

Path parameters

Parameter	Description
`intentId`	The `intentId` returned by `POST /route`.

Request

{
  "txHash": "0x4c8f91363c5f5e3ac2154f94995f5beac2993cc595af552c2681538af627e05d"
}

Send exactly one of txHash and userOpHash. Sending neither or both returns 400 with hash_required.

Field	Required	Description
`txHash`	One of `txHash` or `userOpHash`	The source transaction hash. On EVM chains it is `0x` followed by 64 hex digits. On Solana it is the transaction signature, as the base58 encoding of its 64 bytes.
`userOpHash`	One of `txHash` or `userOpHash`	The userOp hash of a sponsored route, `0x` followed by 64 hex digits. Requires `sponsorshipRequestId`.
`sponsorshipRequestId`	With `userOpHash`	The `requestId` of the route’s `sponsorship` object.
`eoaAddress`	No	The connected wallet (EOA) that originated the payment, when the route executes from a smart account.

The request body is limited to 64 KiB.

The `Idempotency-Key` header

The header is optional. A retry with the same key and a byte-identical body gets back the first response exactly: the same HTTP status and the same body, byte for byte.

The key must be sent once, as 1 to 255 visible ASCII characters. Anything else returns 400 with invalid_request.
A key is scoped to your SDK project and the intent, and is kept for 24 hours.
Only a final response is stored: a 200 or a final refusal. A 5xx or a retryable refusal is not stored, so a retry with the same key runs the commit again.
A retry with the same key while the first request is still running returns 409 with idempotency_key_in_flight. Retry shortly. A request that has held the key for 2 minutes without finishing is treated as dead, and the next request with the key takes over.
The same key with a body that differs in any byte returns 422 with idempotency_key_reused. A change in whitespace or property order counts.

@trustware/sdk sends the transaction hash as the key. Without a key, retries are still safe, because the hash identifies the commit.

Response

{
  "data": {
    "ok": true,
    "transaction_id": "bc5a5e82-1ecb-453b-bf78-c7c3ccdc3223",
    "sourceTxHash": "0x4c8f91363c5f5e3ac2154f94995f5beac2993cc595af552c2681538af627e05d"
  }
}

Field	Description
`ok`	`true` when the commit was accepted.
`transaction_id`	Trustware’s internal transaction record ID.
`sourceTxHash`	The hash the receipt held when this response was first produced. It differs from the hash you sent after a replacement, and on a sponsored route once the bundler includes the userOp, when it becomes the bundle transaction’s hash. A response replayed for an `Idempotency-Key` repeats the first response’s hash, so read the current one from `GET /status`.

Retries

Committing the same hash again returns 200 with the same transaction_id, whatever state the receipt is in. If a commit call fails or times out, send it again with the same hash. Retry a 5xx response the same way.

Committing late

If you broadcast before expiresAt but couldn’t commit in time, commit anyway. Until /status reports "expired", Trustware handles a late commit like an on-time one. Once the intent is expired, Trustware accepts a commit only when it can see the transaction on-chain from the right payer:

On an EVM chain, the transaction is readable on-chain and its sender is verified as the intent’s payer.
On Solana, the transaction is confirmed and its fee payer is the intent’s payer.
For a sponsored route, the bundler has included the userOp.

If Trustware can’t see the transaction yet, you get 409 with tx_not_visible. Retry shortly.

Replaced transactions

If the wallet speeds up or replaces an EVM transaction, commit the new hash. Trustware accepts it once it can see the new transaction on-chain from the same payer and nonce. Until then you get 409 with replacement_not_visible, so retry shortly. The receipt keeps the old hash as history, and committing the old hash again returns 200. Read the current hash from GET /status: a commit response can repeat an old one, as sourceTxHash explains. A replacement is refused with not_a_replacement when Trustware can’t prove it:

The new transaction is visible but does not share the payer and nonce of the committed one.
Trustware never saw the committed transaction on-chain, so it has no nonce to compare.
The committed transaction is already mined.

On Solana, commit a re-signed transaction only after the first one’s blockhash has expired. Until then you get 409 with signature_still_valid, so retry shortly. Trustware accepts the new signature once it is confirmed with the intent’s payer as fee payer. Until then you get 409 with replacement_not_visible. A Solana replacement is refused with not_a_replacement when:

The first signature landed.
The new transaction’s fee payer is not the intent’s payer.
Trustware can’t tell when the first signature stops being able to land. It can tell when the first signature was committed through send-serialized, and for some route-built Solana transactions, which is provider dependent.

A sponsored receipt can’t be replaced. A re-bundle keeps the userOp hash, so any different hash is refused with not_a_replacement. A receipt that has reached a final status never takes a new hash. A different hash returns 409 with receipt_terminal. Build a new route.

Refusal codes

Read code, not error. The error message is for people and its wording can change. Error responses also carry request_id.

{
  "error": "transaction not visible on chain yet",
  "request_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "code": "tx_not_visible"
}

These four codes mean “retry shortly”:

Status	`code`	Meaning
`409`	`replacement_not_visible`	You committed a different hash to a live receipt, and Trustware can’t see the new transaction on-chain yet.
`409`	`signature_still_valid`	You committed a different Solana signature, and the committed signature’s blockhash has not expired, so it can still land.
`409`	`tx_not_visible`	The intent is `expired`, and Trustware can’t see the transaction on-chain from the payer yet.
`409`	`idempotency_key_in_flight`	A request with the same `Idempotency-Key` is still running.

Every other code is final. Don’t retry the same request.

Status	`code`	Meaning
`400`	`invalid_request`	The body is not valid JSON, is over 64 KiB, or the `Idempotency-Key` header is malformed or sent more than once.
`400`	`hash_required`	The body has neither or both of `txHash` and `userOpHash`.
`400`	`user_op_hash_requires_sponsorship`	`userOpHash` was sent without `sponsorshipRequestId`.
`400`	`invalid_tx_hash`	The hash is not in the format of the intent’s source chain.
`400`	`invalid_sponsorship_request_id`	`sponsorshipRequestId` is not a UUID, or names no sponsorship request.
`400`	`invalid_origin_eoa`	`eoaAddress` is not a valid address.
`400`	`payer_mismatch`	The transaction’s on-chain sender is not the intent’s payer.
`404`	`route_intent_not_found`	The intent ID is unknown to your SDK key.
`409`	`tx_hash_committed_elsewhere`	The hash is already committed to another intent. The other intent is never named.
`409`	`not_a_replacement`	A different hash on a live receipt that Trustware can’t prove is a replacement. See replaced transactions.
`409`	`receipt_terminal`	The receipt has reached a final status and the hash is different. Build a new route.
`422`	`idempotency_key_reused`	The `Idempotency-Key` was already used with a different body.

If you never commit

On some routes Trustware watches for the payment itself and commits it for you, for up to 30 minutes after expiresAt. If it has, your own commit of the same hash returns 200 with the same transaction_id. Which routes it watches is provider dependent, and it watches EVM source chains only. These are never covered:

Deposit-address routes.
Payments in a chain’s native token.
Routes whose transaction is a plain ERC-20 transfer call.
Solana routes. Pass routeIntentId to send-serialized to have Trustware commit at broadcast instead.
Transactions not sent from the payer address, such as a smart-account payer whose transaction a third-party bundler submits.

Don’t rely on it. A payment you don’t commit and Trustware doesn’t find is never tracked, so always commit.

Solana: commit at broadcast

If you broadcast through POST /api/v1/sdk/rpc/solana/send-serialized, add routeIntentId to its request body with the intentId. Trustware commits the returned signature at broadcast, under the same rules as this endpoint. routeIntentId needs an SDK key that also holds the intents scope, which this endpoint requires. Without it the request returns 403 with error.code set to SCOPE_NOT_ALLOWED, and the transaction is not broadcast. A failed commit never fails the broadcast response, because the transaction is already out. Commit the signature through this endpoint as well. Retries are safe.

Getting Started

Endpoints

Path parameters

Request

Sponsored transactions

The `Idempotency-Key` header

Response

Retries

Committing late

Replaced transactions

Refusal codes

If you never commit

Solana: commit at broadcast

Path parameters

Request

Sponsored transactions

The Idempotency-Key header

Response

Retries

Committing late

Replaced transactions

Refusal codes

If you never commit

Solana: commit at broadcast

The `Idempotency-Key` header