Concepts

This page defines the terms the rest of the documentation uses. Each term has one meaning throughout.

The record and its hashCopy Anchor Link

Agentic Transaction Record (ATR). The agreement's record: the exact bytes the seller serves; assemble in @integraledger/lcp writes them as one JSON object. It holds the terms the buyer pays under, in whatever form the parties chose. The seller publishes it at an https link before it asks for payment.

ATR hash (H). SHA-256 over the ATR's exact bytes, written 0x followed by 64 hexadecimal digits.

"Exact bytes" is the whole rule. H is computed over the bytes as they arrive, never over a parsed and re-serialised copy. Two documents that mean the same JSON but differ in their bytes (1.0 and 1, "café" and "caf\u00e9", a space after a colon) have different hashes. The gate never parses the ATR: it hashes the bytes it received and compares.

Legal Context Protocol (LCP). The pattern these packages implement: where the payment the buyer approves carries H, that approval is the buyer's acceptance of that exact record; where it does not, the pairing's statement of what it proves says so. The seller advertises H and the link beside its payment request. The buyer confirms that the link serves bytes whose SHA-256 is H. On most pairings, the payment the buyer approves carries H.

Pairings and bindingsCopy Anchor Link

Pairing. A payment protocol, scheme and rail combination, named by an id such as x402/exact/eip155/eip3009: the x402 protocol, its exact scheme, on an EVM chain (eip155), paid with an EIP-3009 transfer authorization. The first segment of the id is the protocol: x402, mpp, card, ap2, ucp, acp or ack.

Binding. How H rides in a pairing's payment: the field of that payment, as the protocol's own specification defines the payment, that carries H. For x402/exact/eip155/eip3009 it is the EIP-3009 nonce: the buyer signs a transfer authorization whose nonce is H. For mpp/charge/solana it is a Memo instruction in the signed transaction. Each pairing has exactly one binding.

In code, a binding is an object exported by @integraledger/lcp. It has an id, a read that finds H and the link in the seller's document, a build that writes H into the payment, and a bound that reads H back out of a completed payment. The Python package carries the same bindings as constants, such as X402_EXACT_EIP155_EIP3009. The pairings reference lists every one.

The buyer gateCopy Anchor Link

Buyer gate. The buyer-side check that compares the served bytes with H before anything is signed. It runs in your process, with your network client and your signer, in four steps:

1. Read. The pairing's binding reads the seller's document: the advertised H, the https link to the ATR, and the payment options.
2. Compare. The gate fetches the link once and computes SHA-256 over the bytes it received. If the result is not H, the gate declines with hash-mismatch, and your signer is never called.
3. Build. Only on a match does the gate build the payment, and it builds it with the hash it computed, not the string the seller advertised. The result is a signing request: exactly what your signer signs.
4. Finish. When your signer answers, the gate completes the payment, and the pairing reads H back from it. The gate returns the payment only when that value is the hash of the bytes it compared, or, where the proof is the agreement payment, without that reading.

transact runs the four steps in one call; for a pairing that needs an agreement payment, its first call returns that payment for your agent's approval, and a second call, with approved, pays. confirm and finish split the steps for an agent whose signer lives elsewhere, such as a hardware wallet or a separate signing service. confirm and finish neither pay nor check the agreement; only transact and agree do. check later confirms that a payment you hold carries, inside it, the hash of the bytes you kept. For a payment with no place for H it declines signed-not-bound, and the agreement receipt is the proof to keep.

How H rides in a paymentCopy Anchor Link

Protocols and rails offer different places for H. Each pairing's binding states its pattern, and what its payment proves:

Three properties follow, and each pairing states them:

• Buyer signs H. Whether what the buyer's wallet signs contains H.
• Binding on chain. Whether the binding is visible on a public ledger after settlement (LCP §8.3): the settlement carries H, part of it, or a value derived from it.
• Public proof. Whether the payment is itself a public proof of H.

Public proof and the agreement paymentCopy Anchor Link

Some payments are not a public proof of H: a card payment, a Stripe charge, a Lightning invoice, a checkout in which the buyer signs nothing. For these pairings the seller's offer also names an agreement URL: an x402 resource for the same H, paid with a pairing whose payment is a public proof, usually for a nominal amount. The agreement payment is a payment like any other: transact returns it for the buyer's agent to approve, pays it once approved, waits for its receipt, and only then signs the main payment. Where the agreement URL answers that the agreement is already recorded, transact takes that receipt without a payment. The receipt is the agreement URL's statement: the gate checks its form and that its atrHash is H, and does not look up the transaction it names. confirm and finish neither pay nor check the agreement; only transact and agree do. The agreement payments guide covers the exchange.

If such a pairing's offer names no agreement URL, the gate declines with agreement-not-offered and signs nothing.

Channels and sessionsCopy Anchor Link

In a payment channel (x402 batch settlement) or a session (an MPP session), one ATR covers the whole channel. The gate compares it once, at the opening. You keep the result as a channel hold: the ATR's bytes, the signed opening and the channel it names. Each later voucher is signed from the hold, under the held hash: an x402 challenge must advertise it, and an MPP session challenge that names another hash or another channel is declined. See channels and sessions.

The partiesCopy Anchor Link

Seller. The party serving the resource. It assembles the ATR, stores it, serves it at the link, and advertises H in its payment request.

Facilitator. The x402 role that verifies and settles a payment for the seller. The gate never talks to a facilitator: it hands the payment back to you, and you send it to the seller.

Signer. Your wallet, or whatever holds your keys. The gate hands it one signing request at a time and never sees a key.

VectorsCopy Anchor Link

Vectors. The shared test cases that fix the rules byte for byte across languages. The TypeScript gate and the Python gate run the same vectors, from the vectors/ directory of @integraledger/lcp, and produce the same hashes, the same requests and the same declines. See vectors.

What the gate does not doCopy Anchor Link

The gate makes sure the payment you sign carries the hash of the bytes you received. It does not:

• read, interpret or judge the ATR's content, which is for you and your principal to judge;
• check the amount, the payee, the asset, the timing or the payer against the ATR (a discrepancy is between the parties);
• carry any business or legal logic;
• hold keys, sign anything itself, or move funds;
• store the ATR: it returns the bytes, and keeping them is yours;
• talk to a facilitator or settle a payment.