Receipts and settlements

A receipt is immutable evidence that a challenge settled on Sui. Delivery of the upstream resource is a separate outcome: keep the receipt even if the HTTP body is missing or the upstream fails after settlement.

On the paid HTTP response

Expect challenge ID, network, payer, atomic amount, asset, and a non-empty Sui transaction digest. Verify the digest on Suiscan (or your network's explorer).

GET /v1/settlements

Authenticated settlement feed for owners and agents.

GET /v1/settlements
GET /v1/settlements?challengeId=<id>
GET /v1/settlements?payer=<address>
GET /v1/settlements?provider=<id>
GET /v1/settlements?resourceId=<id>

Auth

• Owner: verified owner session (wallet personal-message / trusted hop). Scope is the owner's resources and related settlements.
• Agent: OAuth bearer granted the suipay:receipts scope, bound to the connection's payer set. A bearer without that scope receives 403 insufficient_scope.

resourceId filters an owner's own services. On an agent bearer, a resourceId filter returns no settlements; filter by payer or challengeId instead.

Unauthenticated requests receive 401.

Response shape

{
  "count": 1,
  "source": "read-model",
  "settlements": [
    {
      "at": "2026-08-10T12:00:00.000Z",
      "resourceId": "service-id",
      "recipient": "0x...",
      "dialect": "mpp",
      "receipt": {
        "challengeId": "...",
        "txDigest": "...",
        "network": "sui:testnet",
        "payer": "0x...",
        "amount": "250000",
        "asset": "0x...::usdc::USDC",
        "status": "settled"
      }
    }
  ]
}

source is read-model when the gateway has a Postgres read model and memory when it serves its in-process feed. memory rows also carry replayed; read-model rows omit it. Treat absent as not-replayed.

MCP receipts

Remote MCP agents should call the receipts tool after pay. The tool is scoped to the connection's payers so a bearer only sees its own settlements.

What to reconcile after ambiguity

1. Challenge / payment id from the offer.
2. Transaction digest (if known) and finality status on chain.
3. Settlement feed row for that challenge.
4. On-chain PaymentMade / amount / asset / parties when needed.

Only request and pay a fresh challenge after proving the prior attempt did not settle (or after you accept a failed attempt and the work unit rules allow a new authorization).

Refundable offers

If the original offer carried signed refundable terms, settlement may open a RefundVault instead of an immediate merchant transfer. See Settlement and refunds. Ordinary receipts still record the settlement event; refund/release is a later lifecycle.