Status


GET /api/external/attempts/{attemptId}/status

Canonical attempt snapshot. Poll it until a terminal status; webhooks are wake-up signals only, this endpoint is the source of truth.

Response

Settled example:


{
  "apiVersion": "1",
  "attemptId": "attempt_00000000000000000001",
  "intentSessionId": "intent_00000000000000000001",
  "partnerId": "partner-example",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "recipient": "0x1111111111111111111111111111111111111111",
  "status": "settled",
  "expiresAt": "2030-01-01T00:01:00.000Z",
  "evidenceDeadlineAt": "2030-01-01T00:15:30.000Z",
  "submittedAt": 1893456030000,
  "perChainStatus": [
    {
      "chainId": 8453,
      "provider": "relay",
      "submitMethod": "wallet_sendCalls",
      "atomicRequired": true,
      "status": "settled",
      "txHashes": [
        "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
      ],
      "bundleId": "wallet-bundle-example-1",
      "legs": [
        {
          "legIndex": 0,
          "outputTargetId": "output-1",
          "provider": "relay",
          "sourceChainId": 8453,
          "outputSymbol": "USDC",
          "expectedOutputAmount": "9950000",
          "expectedOutputFormatted": "9.95",
          "expectedOutputUsd": "9.95",
          "status": "settled",
          "destinationChainTxHash": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
          "settledAmount": "9.950000000000000000",
          "settledAmountBasis": "estimated",
          "errorCode": "PROVIDER_TRACKING_UNAVAILABLE",
          "errorMessage": "Exact received amount unavailable from provider."
        }
      ]
    }
  ],
  "settledOutputs": [
    {
      "chainId": 42161,
      "symbol": "USDC",
      "amount": "9.950000000000000000",
      "amountBasis": "estimated",
      "txHash": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
    }
  ]
}

Attempt states

`status`	Meaning
`prepared`	Attempt exists; no accepted wallet execution evidence yet
`wallet_submitted`	Wallet evidence was accepted
`provider_pending`	Source execution is confirmed; provider settlement is pending
`settled`	Sweep verified the final output; the target token is in the recipient wallet
`failed`	Execution or settlement failed
`expired`	No reportable execution was accepted before the relevant deadline

Do not infer expiry from prepare expiresAt: status may remain prepared after the signable window while evidenceDeadlineAt is still open.
Top-level failed is an aggregate and does not prove every source chain is terminal. Preserve and continue reporting evidence for an unfinished sibling chain (perChainStatus[]).

Settled outputs

settledOutputs[] contains one entry per successful receive leg:

Field	Meaning
`chainId`, `symbol`	Delivered token identity
`amount`	Decimal token string, not raw units; may carry more fractional digits than the token’s decimals (e.g. `"9.950000000000000000"` for a 6-decimal token). Strict raw-unit parsers throw on the padding — normalize first
`amountBasis`	`actual`: Sweep obtained the exact received amount. `estimated`: delivery settled but the provider could not return the exact amount; `amount` is the best available estimate
`txHash`	Best known destination transaction hash

In the current production pipeline every settled output reports estimated, including provider-confirmed deliveries. Treat estimated as the normal case. Before spending a settled amount programmatically, sum the decimal values with a decimal-safe parser (no floating point), convert to raw units at the contract boundary, and auto-continue only on actual — otherwise resolve the amount from the recipient’s balance and confirm with the user. A conversion helper is in Reference code.

Code


async function pollAttempt(client, attemptId, { intervalMs = 5000 } = {}) {
  const terminal = new Set(['settled', 'failed', 'expired']);
  for (;;) {
    const result = await client.status(attemptId);
    if (result.reachable && result.ok) {
      const snapshot = result.response;
      // Persist the snapshot; update UI from snapshot.status.
      if (terminal.has(snapshot.status)) return snapshot;
    }
    await new Promise((r) => setTimeout(r, intervalMs));
  }
}

404 external_status_failed / execution_attempt_not_found means the attempt does not exist for this partner. Other failure codes: Errors.