Protocol

x402

The seller’s 402 challenge carries the ATR hash and a link to the ATR; on most rails, the payment then carries the ATR hash in a field the rail already has. Source: lcp docs: x402⁠ (opens in a new tab) · Source: lcp docs: rails⁠ (opens in a new tab) The Agentic Transaction Record (ATR) is one record of exactly what was agreed, for one transaction. Its ATR hash, the ATR’s fingerprint, is the proof bound to the transaction: change one byte of the ATR and it no longer matches. Source: lcp docs: the ATR⁠ (opens in a new tab) · Source: lcp docs: the ATR hash⁠ (opens in a new tab)

x402 is a project of the x402 Foundation, under the Linux Foundation. Source: LCP §C.4⁠ (opens in a new tab) Integra is not affiliated; we read their published interfaces.

lcp docs: x402⁠ (opens in a new tab) · lcp docs: rails⁠ (opens in a new tab) · lcp docs: the ATR⁠ (opens in a new tab) · lcp docs: the ATR hash⁠ (opens in a new tab) · LCP §C.4⁠ (opens in a new tab)

The protocol’s own site⁠The standard’s illustration of this protocol (LCP §C.4)⁠

x402

Payment over HTTP 402

The seller’s challenge: The ATR hash and a link to the ATR, in extensions.legalContext.
EVM chains: The ATR hash itself, as the nonce of the transfer authorization the payer signs.
Solana: The ATR hash, written out as text, in the transaction’s Memo instruction.

Run an agentic transaction over x402 now

A real transaction between Integra-managed agents on a test network, then its proof: the agreed terms, bound to the payment.

Loading the demonstrations…

These are real transactions between Integra-managed agents, using testnet funds. Transactions are settled at 1/10,000th of their stated value, for demonstration purposes.

What it is

x402 is HTTP 402 payment: the seller answers a request with a PaymentRequired document listing the options it accepts, and the buyer retries with a payment for one of them. Source: lcp docs: x402⁠ (opens in a new tab)

Version 2 carries an extensions object on the challenge, on the payment and on the settlement response, so a reference placed there comes back on the settlement response as well as the challenge. Source: LCP §C.4⁠ (opens in a new tab)

lcp docs: x402⁠ (opens in a new tab) · LCP §C.4⁠ (opens in a new tab)

Where the ATR hash rides

In the seller’s payment request, beside a link to the ATR. On most chains the payer then signs it as part of the payment.

Exhibit The seller writes the ATR and advertises the ATR hash in the challenge

The standard

Carrying the reference inside x402’s signed Offer and Receipt artifacts is not available today: their EIP-712 types are closed, so it would need an upstream change. Source: LCP §C.4⁠ (opens in a new tab)

The package

Every x402 pairing advertises the ATR hash in the challenge’s extensions.legalContext, with the link to the ATR beside it, and the buyer echoes it in its payment. Source: lcp docs: x402⁠ (opens in a new tab)

The payment then carries it where the rail allows: on EVM chains the payer signs the ATR hash itself as the nonce of its EIP-3009 authorization; on Solana it is the transaction’s Memo instruction; on Stellar, the seller’s muxed address takes the first 8 bytes of the ATR hash as its id. Source: lcp docs: rails⁠ (opens in a new tab)

One document has one legal context: a challenge offering options on several rails carries one ATR hash, H, so the buyer’s payment on any of them is bound to the same ATR. Source: lcp docs: x402⁠ (opens in a new tab)

The ATR’s binding slot also commits to the request the challenge answers (method, path, query and a SHA-256 of the body) and to every option exactly as issued. Source: lcp docs: binding⁠ (opens in a new tab)

The data

Read from the published packages when the site was built; nothing here is typed by hand.

The seller’s challenge for the site’s example sale: H and the link to the ATR, in extensions.legalContext

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.seller.example/v1/market-data"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "40000000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USDC",
        "version": "2"
      }
    }
  ],
  "extensions": {
    "legalContext": {
      "info": {
        "type": "sha256",
        "value": "0x8448dc1b716a5103287cb8f35e36b614ffd91e630ab8b7911833c54748ad5ca6",
        "legalContextUrl": "https://atr.seller.example/k7Qm2V9xT4bN8pR1sW6yZA"
      },
      "schema": {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "type": {
            "const": "sha256"
          },
          "value": {
            "type": "string",
            "pattern": "^0x[0-9a-f]{64}$"
          },
          "legalContextUrl": {
            "type": "string",
            "pattern": "^https://"
          }
        },
        "required": [
          "type",
          "value",
          "legalContextUrl"
        ]
      }
    }
  }
}

The code

Compiled against the published packages when the site is built.

The seller writes the ATR and advertises the ATR hash in the challenge

src/snippets/seller.ts

// The seller, for one sale: write the ATR, hash its exact bytes, and put the ATR hash and the ATR's link in the x402
// challenge it answers the request with.
import { assemble, hash, isRefusal, newAtrId } from '@integraledger/lcp';
import { exactEip3009, requestCommitment, tie, type HttpRequest, type PaymentRequired } from '@integraledger/lcp/x402';

export async function offer(
  challenge: PaymentRequired,
  request: HttpRequest,
  terms: Uint8Array,
  store: (bytes: Uint8Array) => Promise<string>, // your storage: it serves these exact bytes at the link it returns
) {
  const answered = await requestCommitment(request);
  if (isRefusal(answered)) return answered;
  const atr = await assemble(newAtrId(), tie(challenge.accepts, answered), [['terms', terms]]);
  if (isRefusal(atr)) return atr;
  const h = await hash(atr.bytes);
  const link = await store(atr.bytes);
  return exactEip3009.advertise(challenge, h, link, challenge.accepts[0]!);
}

The buyer’s gate compares the ATR with the ATR hash before the wallet signs

src/snippets/buyer.ts

// The buyer's agent, before its wallet signs: the gate fetches the ATR from its link, hashes the exact bytes, compares
// them with the ATR hash the seller advertised, and only then hands the signer a payment that carries it.
import { BINDINGS } from '@integraledger/lcp';
import { transact, type Signer } from '@integraledger/terms';

export async function pay(challenge: unknown, signer: Signer, keep: (atr: Uint8Array) => Promise<void>) {
  const binding = BINDINGS.find((b) => b.id === 'x402/exact/eip155/eip3009')!;
  const result = await transact(challenge, binding, signer, fetch);
  if ('decline' in result) throw new Error(`${result.decline.code}: ${result.decline.detail}`);
  if ('approve' in result) return result; // an agreement payment for the agent to approve first
  await keep(result.bytes); // the ATR it compared, byte for byte
  return result.signed; // the payment, carrying the ATR hash
}

What a payment through it proves

Each pairing’s record states what a payment through it shows, and what it does not, in the package’s own words. These are read from the package when the site is built. Source: lcp docs: pairings reference⁠ (opens in a new tab)

Of these 29 pairings, 23 have the buyer’s signature cover the ATR hash, 23 leave a public proof of it, and 18 let anyone read it back from the chain alone. Source: lcp docs: pairings reference⁠ (opens in a new tab)

Switch to Technical to see each pairing, and the sentence its record states about what a payment through it proves.

lcp docs: pairings reference⁠ (opens in a new tab)

Exhibit Each pairing’s record

The package

Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed an EIP-3009 transfer authorization whose nonce is this ATR's hash. The token contract verified that signature when it executed the transfer, and the hash is on chain as the nonce topic of its AuthorizationUsed event in the settlement transaction. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/eip155/eip3009⁠ (opens in a new tab)
Pattern: Id-Reuse (LCP §8.3.5)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a token authorization whose nonce commits, through the escrow's PaymentInfo, to a salt that is this ATR's hash when unbound, or a commitment over it with the receiver authorizer and policy when bound. The token contract verified the signature when the escrow collected the payment, and the escrow's event carries the salt. When unbound, the salt is this ATR's hash, so the settled transaction itself shows it. When bound, a holder of the ATR, the receiver authorizer and the policy can confirm the hash from the salt; the chain alone does not reveal it. This record covers that first collection; capture, void, refund and reclaim are the operator's and the payer's.
LCP profile: x402/auth-capture/eip155⁠ (opens in a new tab)
Pattern: Id-Reuse (LCP §8.3.5)⁠ (opens in a new tab)
What a payment through it proves: The payment presented a Permit2 authorization whose nonce commits, through the escrow's PaymentInfo, to a salt that is this ATR's hash when unbound, or a commitment over it with the receiver authorizer and policy when bound. The escrow's event in the settlement transaction carries that PaymentInfo, salt included; it does not show which collector funded the payment. When unbound, the salt is this ATR's hash, so the settled transaction itself shows it. When bound, a holder of the ATR, the receiver authorizer and the policy can confirm the hash from the salt; the chain alone does not reveal it. This record covers that first collection; capture, void, refund and reclaim are the operator's and the payer's.
LCP profile: x402/auth-capture/eip155⁠ (opens in a new tab)
Pattern: Protocol Extension (LCP §8.3.6)⁠ (opens in a new tab)
What a payment through it proves: Before this payment, the buyer signed and paid an agreement transaction carrying this ATR's hash on <network>, recorded in <transaction>. The buyer's agent signed, with the HTTP message signature key it registered with Cloudflare, a request whose PAYMENT-SIGNATURE header echoes this ATR's hash in the legalContext entry of x402's extensions. Cloudflare verifies that signature and bills the agent's registered identity off chain. This does not show that amount, asset or timing match the ATR's content.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a token authorization for a deposit into an x402 batch-settlement channel whose identifier, the EIP-712 hash of the channel's configuration, commits to this ATR's hash as the configuration's salt. The token contract or Permit2 verified that signature when the channel contract collected the deposit, and the hash is on chain as the salt in the channel's ChannelCreated event. Each voucher in this channel signs a commitment to this ATR's hash. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/batch-settlement/eip155⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Solana transaction whose seller Memo instruction (`extra.memo`) carries this ATR's hash in LCP string form, and which opened an x402 batch-settlement payment channel; it executed without error. The memo is in the transaction's instruction data on chain. This does not show that amount, recipient, mint or timing match the ATR's content.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer's account authorized an Algorand asset transfer whose note is this ATR's hash in LCP string form, with a signature, a multisignature or a logic signature. The ledger verified that authorization when it confirmed the transaction, which is final on confirmation, and the note is on chain in it. This does not show that amount, receiver, asset or timing match the ATR's content.
LCP profile: x402/exact/algorand/note⁠ (opens in a new tab)
Pattern: HTTP-layer advisory (LCP §8.3.7)⁠ (opens in a new tab)
What a payment through it proves: Before this payment, the buyer signed and paid an agreement transaction carrying this ATR's hash on <network>, recorded in <transaction>. The ATR was assembled before the challenge went out, and the challenge advertised its hash and link. The payer's signed Aptos transaction does not carry the hash. The seller tied the hash to this payment when it claimed it for this request, and identified the settlement as the payer's committed transaction by sender, sequence number and a digest of its transfer. This does not show that the buyer's approval carried the hash, or that amount, payee, asset or timing match the ATR's content.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Cardano transaction whose body commits, through its auxiliary_data_hash, to a CIP-20 message (label 674) carrying this ATR's hash. The ledger included the transaction as valid, at the stated depth; a Cardano transaction with fewer than k blocks after it (2160 on mainnet) can be rolled back. The hash is in the transaction's metadata on chain. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/cardano⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a CEP-3009 transfer authorization whose nonce is this ATR's hash. The token contract verified that signature, and that the signing key is the payer's, when it executed the transfer, and the hash is on chain as the nonce argument of that call. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/casper⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Concordium transaction one of whose transfers carries this ATR's hash, in LCP string form, as its memo. The chain accepted the transaction only with the sender's valid signature, and the memo is on chain in the finalized transfer event. This does not show that amount, payee, token or timing match the ATR's content.
LCP profile: x402/exact/ccd⁠ (opens in a new tab)
Pattern: HTTP-layer advisory (LCP §8.3.7)⁠ (opens in a new tab)
What a payment through it proves: Before this payment, the buyer signed and paid an agreement transaction carrying this ATR's hash on <network>, recorded in <transaction>. The ATR was assembled and delivered before the payment, and the buyer's payment payload echoed this ATR's hash in the legalContext entry of x402's extensions. The buyer's delegation does not sign the hash, and the settlement transaction does not carry it.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The leaf delegation of the permission context redeemed for this payment, made through MetaMask's DelegationManager, carries this ATR's hash as its signed salt. The manager verified every delegation's signature when it redeemed them, and the leaf, with its salt, is in a RedeemedDelegation event in the settlement transaction. The leaf's signer is its delegator, which may be an account the paying account authorised rather than the paying account itself. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/eip155/erc7710-salt⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Permit2 witness transfer whose nonce is this ATR's hash, with the scheme's x402 proxy as spender and the payee in the witness. Permit2 verified the signature when the proxy executed the transfer, and the hash is in the settlement transaction's calldata as the Permit2 nonce; no event carries it. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/eip155/permit2⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Hedera transaction body whose memo carries this ATR's hash in LCP string form. A transaction under that body's id with that memo reached consensus with SUCCESS, and the memo is in the public transaction record; the fee payer, the seller's facilitator, could land another body under the same id. This does not show that amount, recipient, token or timing match the ATR's content.
LCP profile: x402/exact/hedera⁠ (opens in a new tab)
Pattern: HTTP-layer advisory (LCP §8.3.7)⁠ (opens in a new tab)
What a payment through it proves: Before this payment, the buyer signed and paid an agreement transaction carrying this ATR's hash on <network>, recorded in <transaction>. The payment is an x402 transferExecutor payment on Hedera: the payer's executor contract moved the funds under an authorization the seller did not read, and the facilitator submitted the transaction. The hash reached the payer only in the challenge's extension, and nothing the payer signed carries it. The seller read the merged consensus record of the named transaction, and found that its one debited account, by at least one unit, is the payer recorded at claim. This does not show that amount, recipient, token or timing match the ATR's content.
Pattern: native-field, the package’s name for it
What a payment through it proves: Before this payment, the buyer signed and paid an agreement transaction carrying this ATR's hash on <network>, recorded in <transaction>. The seller's node's BOLT11 invoice has this ATR's hash as its payment metadata and x402's request hash as its description hash. Its signature is not verified here, and the payer signed nothing that carries the hash. Settlement is the seller's report; the invoice and its preimage, which the parties hold, show that the invoice was paid; they do not show who paid it, and no public ledger shows the payment. This does not show that amount, payee or timing match the ATR's content.
LCP profile: x402/exact/lnbtc⁠ (opens in a new tab)
Pattern: HTTP-layer advisory (LCP §8.3.7)⁠ (opens in a new tab)
What a payment through it proves: Before this payment, the buyer signed and paid an agreement transaction carrying this ATR's hash on <network>, recorded in <transaction>. The ATR names this payment: its binding slot holds the payment option as issued, including the seller node's signed BOLT11 invoice, whose description hash is x402's request hash. The invoice does not carry this ATR's hash, and the payer signed nothing that does. Settlement is the seller's report; the invoice and its preimage, which the parties hold, show that the invoice was paid; they do not show who paid it, and no public ledger shows the payment. This does not show that amount, payee or timing match the ATR's content.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a NEP-366 delegate action whose one ft_transfer carries this ATR's hash in its memo, in LCP string form. The runtime verified that signature and executed the transfer on the token contract, and the memo is on chain in the delegated call's arguments. This does not show that amount, receiver, token or timing match the ATR's content.
LCP profile: x402/exact/near/memo⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed one Polkadot Asset Hub extrinsic whose bytes end with the profile call, the encoding of a batch of a transfer of the asset and a remark whose bytes are this ATR's hash in LCP string form. The chain verified the signature and dispatched the extrinsic, and its record carries a Remarked event with the BLAKE2b-256 of that remark and a Transferred event of the asset, at the finality recorded. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/polkadot/lcp-assets-remark⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Solana transaction whose one Memo instruction carries this ATR's hash in LCP string form, and the transaction executed without error, carrying a token or SOL transfer. The memo is in the transaction's instruction data on chain. This does not show that amount, recipient, mint or timing match the ATR's content.
Pattern: Native Field, truncated (LCP §B.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed, as SNIP-12 typed data, a SNIP-9 outside execution whose nonce is the low 250 bits of this ATR's hash. The payer's account contract verified that signature when it executed the transfer call, and the nonce is in the settlement transaction's calldata. A holder of the ATR can confirm the hash from the nonce; the chain alone does not reveal all of it, and no event indexes it. This does not show that amount, payee, asset or timing match the ATR's content.
LCP profile: x402/exact/starknet⁠ (opens in a new tab)
Pattern: Native Field, truncated (LCP §B.1)⁠ (opens in a new tab)
What a payment through it proves: The ATR was assembled and delivered before approval, and its hash is in the payment challenge, which the payer did not sign. The payer signed a transfer to the seller's muxed address whose 8-byte id is the first 8 bytes of this ATR's hash, and the transaction succeeded. The id binds this hash only through its first 8 bytes: whoever assembles the ATR can construct a second ATR whose hash begins with the same 8 bytes. This does not show that amount, asset or timing match the ATR's content.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Sui transaction whose one unused Pure input is this ATR's hash. The network executed that transaction successfully, and the hash is on chain in its input list, readable by its digest while a node retains it. This does not show that amount, payee, coin type or timing match the ATR's content.
LCP profile: x402/exact/sui⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Tron transaction whose memo is this ATR's hash in LCP string form, and whose one contract calls transfer on the token. The network verified the signature, which covers the memo through the transaction id. The call succeeded with the token's Transfer event, at the finality recorded. The memo is on chain in the transaction. This does not show that amount, payee, token or timing match the ATR's content.
LCP profile: x402/exact/tron/lcp-trc20-memo⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer's W5 wallet signed a request whose one Jetton transfer carries this ATR's hash in its forward payload, as a TEP-74 text comment in LCP string form. The payer's Jetton wallet executed that transfer, and the Jetton wallet its `internal_transfer` reached accepted it. The comment is on chain in the transfer's message bodies. This does not show that amount, payee, asset or timing match the ATR's content.
Pattern: Id-Reuse (LCP §8.3.5)⁠ (opens in a new tab)
What a payment through it proves: The payer signed, with a single key, an XRPL Payment whose InvoiceID is the SHA-256 of this ATR's hash in LCP string form, and the Payment is in a validated ledger with tesSUCCESS. The hash can be confirmed from the ATR's bytes but not recovered from the ledger alone. This does not show that amount, destination, asset or timing match the ATR's content.
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Permit2 witness transfer whose nonce is this ATR's hash, with the scheme's x402 proxy as spender and the payee in the witness. Permit2 verified the signature when the proxy executed the transfer, and the hash is in the settlement transaction's calldata as the Permit2 nonce; no event carries it. This does not show that amount, payee, asset or timing match the ATR's content. The amount settled is the seller's, submitted by the facilitator the witness names, and at most the signed maximum.
LCP profile: x402/upto/eip155/permit2⁠ (opens in a new tab)
Pattern: Native Field (LCP §8.3.1)⁠ (opens in a new tab)
What a payment through it proves: The payer signed a Solana transaction whose one Memo instruction carries this ATR's hash in LCP string form, and which opened a one-request payment channel escrowing the signed maximum; it executed without error. The memo is in the transaction's instruction data on chain. The amount charged from the escrow, which may be zero, is the seller's metering, settled by the facilitator in a later transaction that does not carry the hash, and the rest returns to the payer. This does not show that amount, recipient, mint or timing match the ATR's content.

Where a sentence names <network> and <transaction>, the pairing’s record fills them in: they name the agreement payment the buyer made first. Source: lcp docs: pairings reference⁠ (opens in a new tab) · Source: lcp docs: the agreement URL⁠ (opens in a new tab)

The rails it settles on

Ready to see your own agreements proved?

Tell us what you sell, buy or carry, and we will show you where the agreement rides in it.

Integra Binder, hosted by Integra, does the seller’s side of each agreement and is free on test networks, with test-network USDC.

Talk to us