> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 receipt adapter

> algovoi-x402-receipt-adapter turns an x402 payment into an offline-verifiable settlement attestation, facilitator or origin side, and binds it into the Keystone.

x402 proves a payment happened with a transaction hash, but it carries no
receipt format, so verifying a settlement later means going back to the chain.
`algovoi-x402-receipt-adapter` closes that gap. It turns an x402 payment into a
[settlement attestation](/settlement-attestation): a small JSON object
canonicalised under [RFC 8785 (JCS)](https://www.rfc-editor.org/rfc/rfc8785) and
content addressed with SHA-256, that any party recomputes and verifies offline
with a JSON parser, JCS, and SHA-256 alone. No issuer call, no account, no
service.

## What it produces

```
PAYMENT-REQUIRED / PaymentRequirements   ->  maxAmountRequired, asset, payTo
PAYMENT-RESPONSE / SettleResponse        ->  transaction, network, payer, amount
                                 |
   x402_payment_ref = "sha256:" + SHA-256(JCS({txHash, networkId, payer,
                                               amount, currency, settled_at_ms}))
                                 |
   settlement_attestation_v1   (settlement_ref content addresses the receipt)
```

* `x402_payment_ref` binds the settlement transaction to the requested amount and
  currency plus a timestamp, so a transaction hash can no longer be re-bound to a
  different amount.
* `settlement_ref` is `"sha256:"` + SHA-256(JCS(attestation)), the content address
  of the whole receipt. Recompute it in any language and it matches byte for byte.

## Three ways to capture

Every option produces the same `settlement_ref` for the same underlying payment.

| Option      | Function                            | Use when                                                                                              |
| ----------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Facilitator | `receipt_from_settle`               | you run an x402 facilitator, and emit the receipt from your own `SettleResponse` at settle time       |
| Origin      | `capture_x402_settlement`           | you sit behind a managed gateway, and re-verify the transaction on chain (fail closed) before issuing |
| Direct      | `build_x402_settlement_attestation` | you already hold both headers and trust them                                                          |

Settlement fields follow the x402 Foundation `SettleResponse` model
(`transaction`, `network`, `payer`); the legacy names `txHash` and `networkId`
are accepted as aliases.

```python theme={null}
from algovoi_x402_receipt_adapter import receipt_from_settle

result = receipt_from_settle(
    payment_requirements,          # maxAmountRequired, asset, payTo
    settle_response,               # success, transaction, network, payer, amount
    settled_at_ms=1751472000000,
    provider_did="did:web:your-service.example",
)
result["settlement_ref"]     # "sha256:..."
result["confirmed_amount"]   # actual settled amount recorded
```

## Bind it into the Keystone

The settlement binds into the [Keystone](/keystone) accountability chain with the
published `algovoi-substrate` binding primitive, introducing no new hashing. One
call ties a payment to the verified agent action that authorised it, so an x402
payment becomes part of an offline-verifiable record that runs from identity
through to settlement.

```python theme={null}
from algovoi_x402_receipt_adapter import to_keystone_binding

binding_ref = to_keystone_binding(
    result,
    action_ref="...",            # the verified agent action
    transition_hash="...",       # the committed lifecycle transition
    retention_chain_ref="sha256:...",
)
```

```
binding_ref = "sha256:" + SHA-256(JCS({action_ref, transition_hash,
                                       settlement_ref, retention_chain_ref}))
```

A worked example, the Keystone carried all the way through real settlements, is
on the [proven on-chain](/keystone-proof) page.

## Install

Apache License 2.0. manylinux wheels for Python 3.11 to 3.13, from the AlgoVoi
index:

```bash theme={null}
pip install --extra-index-url https://pip.algovoi.co.uk/simple/ algovoi-x402-receipt-adapter
```

## Verify offline

```python theme={null}
from algovoi_x402_receipt_adapter import verify_settlement_ref

verify_settlement_ref(result["attestation"], result["settlement_ref"])  # True
```

The check is pure and deterministic: `"sha256:"` + SHA-256(JCS(attestation)).
Recompute it with any RFC 8785 canonicaliser and a SHA-256 and the reference
matches. No trust in AlgoVoi is required.

## See also

* [Verifiable x402 receipts](/verifiable-x402-receipt) the receipt discipline this produces
* [Settlement attestation](/settlement-attestation) the evidence format
* [The Keystone](/keystone) the trust chain it binds into
* [Proven on-chain](/keystone-proof) the Keystone carried through real settlements