Skip to main content
REST broadcasts create persisted transaction records that Para tracks to terminal status on-chain. Records are queryable, auditable, and emit webhooks when they confirm or fail. Rows are written for POST /v1/wallets/{walletId}/transfer broadcasts and for POST /v1/wallets/{walletId}/sign-transaction when broadcast: true. Sign-only calls do not write rows. Yield operations also write one record for each signed approval or Aave action. The gas sponsorship pilot creates a record when Para accepts the transfer, before signing or submission. This includes transfers awaiting policy review.

Status Lifecycle

Legacy broadcasts use this lifecycle. Sponsored differences follow the table.
Legacy EVM transfer and sign_transaction records require a canonical receipt with at least two confirmations and a block at or below the RPC’s finalized head before resolving. An SDK socket notification of inclusion may arrive earlier. Missing receipts, noncanonical blocks, RPC errors, and unavailable finality evidence remain unresolved. Solana broadcasts resolve after the signature status reaches finalized. For sponsored operations, submitted with stage included means the operation is on-chain but awaits receipt verification. A successful operation with verified token delivery becomes confirmed; an included execution revert becomes reverted. An unknown submission stays nonterminal. An included operation with unresolved token-delivery evidence stays pending with stage delivery_unverified until reconciled.
Partner code must treat unknown status values as non-terminal. Para may add new statuses (finalized, replaced) in a later release without bumping the API version.

Response Shape

Calls that broadcast return a transactionId field and set an x-transaction-id response header. Use either to look up the record afterward.
For sign-transaction, omitted broadcast is also sign-only. No record is written and no transactionId is returned.
If a legacy broadcast request fails after Para creates the transaction row, the error response still sets x-transaction-id and includes transactionId in the JSON body. Legacy failures after signing can also include signedTransaction. Sponsored responses never expose signed payloads. Use the stored transaction for failure details. Eligible sponsored transfers receive HTTP 202 from transfer, including on a replay of the original request and key:
sponsored-transfer-response.json
Both lookup and list responses include executionMode for sponsored operations. Individual lookup also adds stage and optional reviewId, userOperationHash, and actualGasCost; list responses contain transaction summaries. The hash field remains the on-chain transaction hash; a UserOperation hash never replaces it. actualGasCost records the individual operation’s settled cost in native-token base units, including included reverts. Keep it as a decimal string or bigint. Stage requires_action pauses for policy review; call the explicit resume endpoint after approval. Stage submission_unknown means submission may have happened. Neither an unknown submission nor delivery_unverified permits resending with a new key. See Gas sponsorship.

Reading Transaction History

List transactions for a wallet

Filter by status via ?status=. Filter by source operation via ?intentKind=transfer or ?intentKind=sign_transaction, or ?intentKind=yield. Paginate via ?cursor= using the opaque cursor returned in each response. Results are ordered by createdAt DESC.

Look up a single transaction

Records that belong to a different partner return 404 with an identical body to missing records. GET and list responses provide the latest persisted outcome. A replay with the original Idempotency-Key can return the cached submission or error response; it does not refresh transaction status. Keep the original transactionId and use its lookup endpoint to track reconciliation.

Record Fields

Each record includes intentKind, transfer, sign_transaction, or yield. For EVM sign_transaction records, Para stores chainId, to, and value when value was present in the request. tokenAddress is absent. Para does not decode calldata. For Solana sign_transaction records, to, value, and tokenAddress are absent because Para does not decode arbitrary Solana instructions.

Monitoring and delayed outcomes

Legacy EVM and Solana transfer and sign_transaction broadcasts retain submitted after the 30-minute active monitoring window. Para stores unresolved context and checks the chain less frequently, including after a restart. Timeout alone emits no failed webhook and does not release spend reservations. Do not send the payment again because monitoring timed out. The optional monitoring object appears in lookup and list responses: After 24 hours, unresolved monitoring becomes escalated. Checks continue with backoff capped at one hour; escalation is an operational follow-up, not chain expiry. Contact Para support with the transactionId if the record remains unresolved or reports missing_context or unavailable finality evidence. An advanced sender nonce without an identified winning transaction stays unresolved. When Para verifies a linked same-nonce winner, the original record keeps its hash and becomes failed with failureCode: "REPLACED" or "CANCELLED". Use monitoring.chainOutcome, winningHash, and winningStatus to distinguish the original transaction’s status from the winning transaction’s result.

Polling Recipe

Poll until a terminal result or a required review. A local polling timeout does not mean execution failed; save the tracking ID and continue checking later. Do not submit a replacement transfer because polling timed out.
wait-for-confirmation.ts

Webhooks

Subscribe to two event types from the Developer Portal to receive terminal-state notifications automatically: Sponsored terminal notifications follow operation-level validation and receipt verification. Fetch persisted transaction status to reconcile missed notifications; webhook delivery is not a substitute for checking unresolved operations. Webhook bodies use the standard envelope described in the webhooks guide. The data.transactionId field matches the transactionId returned by transfer or sign-transaction with broadcast: true. Payload data example for rest.transaction.confirmed:
rest.transaction.failed mirrors the shape and adds status (reverted or failed), plus optional failureStage, failureCode, and failureMessage fields. Reconciliation notifications may also include chainOutcome, winningHash, and winningStatus. The payload’s hash remains the original transaction hash. Delivery is at least once with a stable event ID; deduplicate using the webhook-id header. Before applying a delayed event, fetch the transaction record to avoid overwriting a newer outcome. A monitoring deadline alone does not emit rest.transaction.failed.

Backend receiver pattern

Mobile and web clients do not receive REST transaction webhooks directly. Your backend receives the webhook, verifies it with the secret from the Developer Portal, updates its transaction row, and exposes the latest status to the client. In this example, verifyParaWebhook is the HMAC check described in the webhooks guide.
webhook-route.ts
Store the transactionId when you submit the REST broadcast. In the webhook, use event.data.transactionId to update that same row.
Sign-only calls and transactions you broadcast yourself do not emit REST transaction webhooks. Para only sends these webhooks for broadcasts it can monitor.

Failure Fields

When status = failed, failureStage describes where the pipeline broke: A lost RPC response can leave the record and webhook showing failed / broadcast even if the transaction was accepted. GET may still return that failed record. Reconcile the original hash and nonce, or contact Para support, before sending another payment. Historical failed / monitor_timeout rows remain uncertain until a chain-evidence reconciliation corrects them. Para previews historical corrections before applying a backfill. A later success or revert updates GET/list and emits the appropriate outcome webhook. The historical backfill leaves other failed records unchanged. Fetch the current record before acting on an older timeout webhook; a cached request replay may still contain the earlier response.

Rollout compatibility

Apply the additive migration and replace older REST monitor processes before relying on this reconciliation contract. Older processes can still emit failed / monitor_timeout events during a rollout; treat those as unresolved until reconciled. If rolling back, retain the monitoring columns, checkpoints, and pending outcome notifications so new workers can resume later. Historical timeout records without a checkpoint require an explicit chain-evidence preview and backfill; they are not automatically corrected. When status = reverted, the transaction reached the chain and execution failed. blockNumber and, for EVM, blockHash are populated; failureStage is absent. failureMessage contains any error detail surfaced by the monitor.

Broadcast Error Messages

REST /transfer now sources broadcast-failure messages from Para’s shared broadcast helper rather than passing through raw ethers.js strings. If code parses the previous raw string format, update it to read failureCode (e.g. INSUFFICIENT_NATIVE_BALANCE, EXECUTION_FAILED) from the transaction record or failure webhook instead.

Yield transactions

Yield records use intentKind: "yield" and follow the yield operation’s recovery process. A broadcast timeout does not mark a yield transaction as failed or trigger a new signature. Para continues tracking the stored signed transaction. Yield confirmations require two confirmations of the canonical block, which is not finality. Webhooks describe individual steps. Use the yield operation status to distinguish a confirmed token approval from a completed deposit or withdrawal.

Retention

Both /transfer broadcasts and sign-transaction calls with broadcast: true write rows. Retention remains deferred until the rest_transfers table reaches an agreed large-row or disk threshold.