Transaction History

Persisted transaction records, on-chain monitoring, and webhooks for REST API broadcasts

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.

Ordinary Solana broadcasts validate the recent blockhash before signing or creating a record. If the RPC cannot find the blockhash, the request returns 400 BLOCKHASH_NOT_FOUND; refresh the transaction’s blockhash before retrying. A temporary RPC validation failure returns 503 RPC_UNAVAILABLE. These errors have no transaction ID because signing has not started.

Durable-nonce messages validate the initialized nonce account and save its value before signing. An invalid or changed nonce or invalid lookup table returns 400 INVALID_NONCE. Finalized nonce advancement or account closure can later permit a new managed transfer while preserving the earlier transaction’s unknown outcome.

The gas sponsorship pilot creates a record when Para accepts the transfer, before signing or submission. This includes transfers awaiting policy review.

Automatic fee retry also creates a record before signing. Its 202 response and single-transaction lookup include autoRetry metadata. The original payment and its EVM fee replacements or Solana rebuilt attempts share one transactionId. A stopped retry process can still have an unresolved chain outcome.

Status Lifecycle

Legacy broadcasts use this lifecycle. Sponsored differences follow the table.

pending → submitted → confirmed
                    → reverted
                    ↘ failed

Status	Meaning
pending	Record inserted; broadcast not yet attempted.
submitted	RPC accepted the signed bytes. Active monitoring or durable reconciliation continues. Nonterminal.
confirmed	Verified successful chain outcome. blockNumber and, for EVM, blockHash are populated.
reverted	Verified execution failure on-chain (EVM status=0 or Solana signature error). Terminal.
failed	Signing or broadcast failed, or an identified same-nonce transaction superseded the original. Check failureStage, failureCode, and monitoring.

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.

{
  "signedTransaction": "0x02f8...",
  "txHash": "0x1234abcd...",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000"
}

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.

Sponsored responses

Eligible sponsored transfers receive HTTP 202 from transfer, including on a replay of the original request and key:

sponsored-transfer-response.json

{
  "executionMode": "sponsored",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending"
}

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

curl -H "X-API-Key: $PARA_API_KEY" \
  "https://api.beta.getpara.com/v1/wallets/$WALLET_ID/transactions?status=confirmed&limit=20"

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

curl -H "X-API-Key: $PARA_API_KEY" \
  "https://api.beta.getpara.com/v1/wallets/$WALLET_ID/transactions/$TX_ID"

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. Legacy broadcast replays with the original Idempotency-Key can return the cached submission or error response; they do 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 continues checking the chain, 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:

Field	Meaning
state	active, reconciling, escalated, or resolved.
timedOutAt	When active monitoring handed off to durable checks.
lastCheckedAt	Time of the most recent reconciliation check.
reason	pending, nonce_consumed, noncanonical, insufficient_confirmations, awaiting_finality, missing_context, or rpc_error.
chainOutcome	Verified success, revert, replacement, or cancellation. Absent while unresolved.
winningHash	Identified EVM transaction that used the original sender and nonce, or the finalized Solana attempt for a managed payment.
winningStatus	That transaction’s verified confirmed or reverted result.

During the first 24 hours, healthy pending checks stay at most five minutes apart. Once Para observes receipt or signature evidence, subsequent checks for finality, confirmations, or canonical chain evidence run every 60 seconds, regardless of transaction age. RPC errors and missing context use backoff capped at one hour.

After 24 hours, unresolved monitoring becomes escalated and still-pending checks can also back off to one hour. Escalation does not expire the transaction. Contact Para support with the transactionId if the record remains unresolved or reports missing_context or unavailable finality evidence.

For managed automatic retry, a verified Para EVM fee replacement or Solana attempt resolves the same payment as confirmed or reverted. The original hash stays unchanged; monitoring.winningHash identifies the included attempt. Fee attempts and stopped retry processing are available through the single-transaction lookup. Stopped EVM operations with no saved hash still check the finalized account nonce. To consume an unused nonce, use the manual cancellation flow. The cancellation has its own transaction record; the original payment stays blocked until finality.

A stopped Solana payment becomes failed with failureCode: "TRANSACTION_EXPIRED" only when every signed attempt is proven expired without landing. Incomplete finalized history or an unknown signing outcome retains the unresolved payment and wallet hold.

An advanced EVM sender nonce without an identified winning transaction leaves the payment outcome unresolved. When Para verifies an unrelated 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

async function waitForConfirmation(walletId: string, transactionId: string) {
  const start = Date.now();
  let delayMs = 2000;
  const timeoutMs = 10 * 60 * 1000;

  while (Date.now() - start < timeoutMs) {
    const res = await fetch(
      `https://api.beta.getpara.com/v1/wallets/${walletId}/transactions/${transactionId}`,
      { headers: { 'X-API-Key': process.env.PARA_API_KEY! } },
    );
    if (!res.ok) throw new Error(`Transaction lookup failed: ${res.status}`);
    const record = await res.json();

    if (record.stage === 'requires_action' || record.stage === 'delivery_unverified') return record;
    const historicalTimeout = record.status === 'failed' && record.failureStage === 'monitor_timeout';
    if (!historicalTimeout && ['confirmed', 'reverted', 'failed'].includes(record.status)) {
      return record;
    }
    await new Promise((r) => setTimeout(r, delayMs));
    delayMs = Math.min(delayMs * 1.5, 15000);
  }
  throw new Error('timed out waiting for confirmation');
}

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.

Event	When it fires
rest.transaction.confirmed	Para verified the successful chain outcome, including a late confirmation.
rest.transaction.failed	Para verified a revert or same-nonce winner, or recorded a signing/broadcast failure.

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:

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "walletId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "partnerId": "11111111-2222-3333-4444-555555555555",
  "intentKind": "transfer",
  "type": "EVM",
  "hash": "0x1234abcd...",
  "blockNumber": "5127103",
  "blockHash": "0xdeadbeef...",
  "resolvedAt": "2026-04-23T12:00:00.000Z"
}

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

app.post("/webhooks/para", express.raw({ type: "application/json" }), async (req, res) => {
  if (!verifyParaWebhook(req.body, req.headers, process.env.PARA_WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));

  if (event.type === "rest.transaction.confirmed" || event.type === "rest.transaction.failed") {
    const lookup = await fetch(
      `https://api.beta.getpara.com/v1/wallets/${event.data.walletId}/transactions/${event.data.transactionId}`,
      { headers: { "X-API-Key": process.env.PARA_API_KEY! } },
    );
    if (!lookup.ok) return res.sendStatus(503);
    const record = await lookup.json();
    await db.transactions.update(event.data.transactionId, {
      status: record.status,
      txHash: record.hash,
      blockNumber: record.blockNumber,
      failureStage: record.failureStage,
      failureCode: record.failureCode,
      failureMessage: record.failureMessage,
      monitoring: record.monitoring,
      resolvedAt: record.resolvedAt,
    });
  }

  res.sendStatus(204);
});

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:

Stage	Meaning
mpc_sign	The MPC signing ceremony errored before a signature was produced.
signature_apply	The signature could not be attached to the transaction.
signer_verify	The recovered signer address did not match the wallet’s public address (EVM only).
broadcast	The broadcast request failed because of an RPC rejection or transport error.
monitor_timeout	Historical tracking deadline. It does not establish chain failure, cancellation, or expiry.

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.