What should I do when settlement is unknown?

Reconcile the original Agent Payment Intent after a paid request times out or returns unreliable settlement evidence without risking a duplicate payment.

Stop payment retries and reconcile the original Intent. settlement_unknown means an authorized payment may already have reached the x402 Facilitator, but the available response and onchain evidence cannot yet prove whether it settled.

It does not mean “unpaid,” and it is never permission to create a replacement Intent, authorization, idempotency key, or nonce.

When this state occurs

After the control plane issues an authorization, the customer signer produces the exact payment signature and the Agent SDK sends the paid request. Settlement can become unknown when, for example:

the paid request times out after leaving the Agent runtime;
the connection closes before a reliable response arrives;
the resource response contains missing or malformed settlement evidence; or
the Facilitator, resource server, RPC provider, and chain temporarily provide incomplete or conflicting evidence.

At that point the payment may have succeeded even though the Agent did not receive the resource response.

Recovery procedure

Persist the intentId and authorizationId from SettlementUnknownError.
Stop automatic payment retries for that business purchase. Do not rotate the idempotency key.
Query the original Intent with agent.getPayment(intentId) or management.payments.get(intentId).
Subscribe to signed agent_payment.settlement.* and agent_payment.resource.* Webhooks, deduplicating them by event ID.
Keep the business task in an explicit pending or reconciliation state until the original Intent reaches a definitive outcome.
If the state remains unknown beyond your operational threshold, escalate it for investigation; do not turn the alert into an automatic repayment.

The Agent SDK exposes the identifiers on the error:

import { SettlementUnknownError } from '@stableops/agent-sdk'

try {
  await agent.x402Fetch(resourceUrl, {
    idempotencyKey: 'research-task-284:market-report:v1',
  })
} catch (error) {
  if (error instanceof SettlementUnknownError) {
    await saveForReconciliation({
      intentId: error.intentId,
      authorizationId: error.authorizationId,
    })

    const payment = await agent.getPayment(error.intentId)
    console.error({
      intentId: payment.intentId,
      paymentStatus: payment.status,
      resourceStatus: payment.resourceStatus,
    })
  }

  throw error
}

Querying the record is safe. Calling x402Fetch as a new purchase with a different idempotency key is not.

How the state can resolve

Final evidence	Payment outcome	What your application should do
The authorization nonce was used and the matching transfer is confirmed	`settled`	Record the payment once; inspect the separate resource status before deciding whether the business task completed
Reconciliation proves the settlement was reverted	`reverted`	Record the failed payment outcome and require an explicit operator or business decision before any new purchase
The grant and payment authorization expired, the nonce is unused, and no matching transfer exists after sufficient scanning	`expired`	The committed budget can be released; a later purchase must be a new deliberate attempt
Chain or provider evidence is still unavailable	`settlement_unknown`	Keep reconciling and keep the budget committed

StableOps does not release committed budget merely because a wall-clock timeout elapsed. It must first establish that the authorization expired unused and that no matching transfer is pending. This conservative rule prevents the same funds from being counted as available while the first payment may still settle.

Payment and resource outcomes are separate

Even after payment settlement becomes known, the resource outcome may remain unknown or failed:

settled plus response_received means payment and the paid HTTP exchange both have reliable evidence.
settled plus unknown means funds moved but the Agent may not have received the resource.
A resource response can arrive before StableOps has confirmed settled onchain.

Resolve resource delivery through the seller's replay, support, or business-compensation process. Never interpret a missing resource as proof that no payment occurred.

What should I do when settlement is unknown?

When this state occurs

Recovery procedure

How the state can resolve

Payment and resource outcomes are separate

Related

On this page