Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

9.9 KB
Raw Blame

Pending settlement: the third answer an x402 settle can give

An x402 payment has three moving parts: the 402 challenge, the buyer's signed payment, and the settlement that puts that payment on chain. For most of x402's short life the last step had two possible outcomes, success or failure, and that is one outcome short of the truth.

A Solana transaction is broadcast and then confirmed. Those are separate events seconds apart, and between them the outcome is genuinely unknown: the transaction may be about to land, may already have landed on a node that has not answered yet, or may have been dropped. A settle that has to answer immediately has to guess, and the old answer was "failed".

That guess is expensive in both directions. Report failure and a buyer whose USDC is about to move is told they were not charged and handed no product. Report success and you have promised a settlement that may never happen.

Since 2026-09-17 the Solana x402 facilitators, ours included, answer with a third state instead:

{
  "success": false,
  "errorReason": "settlement_pending",
  "transaction": "5Kd...a1c"
}

Read it as: broadcast, outcome unknown, ask again. It is not a failure, and the canonical SDKs treat it as retryable rather than surfacing it as an error. This page documents how three.ws implements it on both sides of the wire.

What changes for you as a buyer

Nothing, if you use a current x402 client library: @x402/fetch, @x402/axios, @x402/mcp and the Go server retry a pending settle for you.

If you speak the protocol by hand, two rules:

  1. Do not treat settlement_pending as a failed payment. Retry the settle with the identical payload, requirements, and Idempotency-Key. That identity is what lets the facilitator recognise your retry and reconcile against the transaction it already broadcast. A changed key or payload asks it to verify and broadcast a second transaction, which is how an unknown outcome turns into a double charge.

  2. Retry once, then read the response. Our paid endpoints deliver the good on a pending settlement and tell you so in the X-PAYMENT-RESPONSE header:

    { "success": true, "status": "pending", "transaction": "5Kd...a1c", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "payer": "..." }
    

    status: "pending" means your response body is real and complete, and the settlement is still confirming. transaction is the signature to watch on any Solana explorer. You do not need to pay again, and you must not: the authorization you signed is single-use and already spent.

Every other settle response is unchanged. A settle that genuinely failed still says so, with a reason you can act on.

What it does on our rail

The facilitator: never guess, never re-broadcast

self-facilitator.js settles Solana payments in house: it validates the buyer-signed transfer, co-signs the fee payer, broadcasts over our own RPC, and waits for confirmation. The wait now distinguishes three answers rather than two.

Chain says Verdict Response
Landed, no error confirmed success: true
Landed with an on-chain error terminal failure success: false, not_confirmed:<err>
Dropped: blockhash expired, never observable terminal failure success: false, abandoned at reconcile
Wait ran out, or the RPC could not answer unknown settlement_pending + signature

Only the last row is pending. A transaction that ran and reverted is a failure and always was; an RPC that returns 429 tells you nothing about a transaction and must never be read as a rejection. That distinction is the whole mechanism: if "unknown" is allowed to absorb real failures, pending becomes a way of never answering.

A pending answer also carries an obligation, so the facilitator records the broadcast signature before it answers, keyed by a hash of the signed transaction. Two things follow:

  • A retry reconciles instead of re-broadcasting. A settle whose payload matches a recorded signature skips validation, balance reads, fee metering, co-signing and broadcast entirely, and simply re-awaits that signature. One authorization produces one transaction, ever.
  • A pending answer that cannot be recorded is downgraded to a failure. Answering pending promises that a retry can reconcile, and with no record it cannot. The reason becomes settlement_pending_unrecordable and still carries the signature, so the payment can be reconciled by hand.

The store lives in Postgres (pending-settlements.js), not in process memory. The x402 SDK's default PendingSettlementStore is a per-process Map, which only works when the retry happens to land on the same instance; our API runs several Cloud Run replicas with no session affinity, so an in-memory store would miss most retries and re-broadcast instead of reconciling. This is exactly the case the SDK made the store an interface for.

The resource server: deliver, then finish the accounting

settlePayment retries a pending settle exactly once, with the same body and key. If the retry resolves, the payment is ordinary. If it does not, the settle returns status: 'pending' rather than throwing, the endpoint delivers the good, and the row is handed to reconciliation.

Exactly one retry, never a loop: this runs inside a buyer's open HTTP request, and any bounded waiting belongs to the facilitator's own confirmation window.

Delivering against an unconfirmed payment is a deliberate trade, and it is bounded by two things. The payment was simulated at /verify before the handler ran (a payment that cannot settle never reaches the work), and the settlement is already broadcast, so the overwhelming majority land within seconds. What makes the trade acceptable rather than reckless is that it is never silent: the settlement credit is not claimed, the SOL fee is not metered, and the payment is recorded with settlement_status = 'pending' (so revenue queries, which count success, do not include it) until the chain answers.

One thing does fire on a pending settlement: a route's own post-settlement accrual hook, such as the author royalty on /api/x402/skill-call. That is deliberate, so an author is paid promptly rather than on the reconcile cadence, and every accrual carries the settlement signature as provenance, so the rare abandoned settlement can be traced to the accrual it produced.

Reconciliation: the books close either way

/api/cron/x402-settlement-reconcile runs every two minutes over the open rows. It is strictly read-only on chain: it never signs and never re-sends.

  • Confirmed → claim the settle credit under the same idempotency key the settle used, so settle-credit.js grants it at most once per signature, with the fee the chain actually charged, and promote the payment's audit row from pending to success so it enters the revenue figures.
  • Failed or abandoned → close the row and mark the audit row failed. If the good had already been delivered, raise an ops alert naming the signature, the resource, and the payer. This is the one case the design can cost us, so it is never quiet.
  • Still unknown → bump the attempt count and look again next pass. A signature the ledger has never seen is only written off once its blockhash can no longer be valid (180s), because before that "not found" means "not yet".

Resolved rows are pruned after 30 days by the storage sweep; an unresolved one is never pruned, because it is a payment nobody has accounted for yet.

GET /api/x402-status reports the live picture under settlements:

{ "settlements": { "window_hours": 24, "pending": 0, "confirmed": 141, "failed": 0, "abandoned": 0 } }

A non-zero pending is normal and self-clearing. A climbing pending with abandoned or failed beside it is not a payment problem: it means settlements are being broadcast into conditions where they cannot confirm, which points at RPC health or a sponsor wallet that cannot cover fees.

Latency, which is the other half of the story

The old confirmation wait was 30 seconds, because a wait that ran out became a 502 and a 502 had to be avoided at almost any cost. Once an unresolved wait is a third outcome instead of a failure, holding a buyer's connection open that long buys nothing. The wait is now 12 seconds with an 800ms poll, which clears the overwhelming majority of confirmations inline and caps the settle leg of a paid request at a latency a client library will sit through. Anything slower goes pending and finishes out of band.

Operators can move it without a deploy:

# Shorter wait: more settles go pending, each request returns sooner. Useful
# while an RPC provider is degraded.
gcloud run services update three-ws-api --region us-central1 \
  --update-env-vars X402_SETTLE_CONFIRM_TIMEOUT_MS=6000

Why this matters beyond one status string

The binary was not just imprecise, it was the single largest source of false failure on the rail. not_confirmed:confirm_timeout was reported as a settle failure and answered with 502, which every buyer, every trust monitor, and every one of our own pipelines read as a broken endpoint, on payments the chain was in the middle of accepting. The third state does not make settlement more reliable; it makes our report of it true.

Related