TypeScript API

Everything on this page is exported from @integraledger/terms. The package is ESM only and needs Node.js >=26.11.1. Bindings, one per pairing, are exported by @integraledger/lcp; the pairings reference names each one.

No function throws for a protocol outcome. Each returns its result or a Declined.

FunctionsCopy Anchor Link

transactCopy Anchor Link

import type { AtrHash } from "@integraledger/lcp";
import type {
  AgreementReceipt,
  Binding,
  Declined,
  Fetch,
  Presented,
  Signer,
  ToApprove,
  TransactOptions,
} from "@integraledger/terms";

declare function transact(
  doc: unknown,
  binding: Binding,
  signer: Signer,
  fetch: Fetch,
  options?: TransactOptions,
): Promise<
  | { signed: Presented | null; landed?: unknown; bytes: Uint8Array; h: AtrHash; agreement?: AgreementReceipt }
  | ToApprove
  | Declined
>;

confirm, then, for a pairing whose payment is not itself a public proof, the agreement, then the signer, then finish. Without options.approved, an agreement not yet recorded is returned as { approve, bytes, h }: the agreement payment for the agent to approve, with nothing signed. With options.approved, the value of approve carried back unchanged, that payment is signed and paid as agree pays it, and the payment for the resource is signed only with the agreement's receipt in hand. On a decline before the signer, the signer is never called. signed is null when the pairing gives the buyer nothing to sign. agreement is the agreement's receipt, where the pairing needs one; landed where finish gives one. options.signal ends the agreement exchange. Options holding anything but inputs, agreementSigner, approved and signal, or a member of the wrong kind, and a signer or agreementSigner whose account is not a string, are declined before any fetch.

The agreement payment is shown before it is signed: transact returns it with its amount, asset, payee and network, and signs it only when a second call carries it back. The payment for the resource is handed to signer directly; approving it is your agent's step before it calls transact. The gate applies no spending limit. Once the agreement payment is sent, a decline is agreement-pending with the payment as moved: see agree for collecting its receipt.

confirmCopy Anchor Link

import type { AtrHash } from "@integraledger/lcp";
import type { Binding, Chosen, Declined, Fetch, Inputs, SigningRequest } from "@integraledger/terms";

declare function confirm(
  doc: unknown,
  binding: Binding,
  account: string,
  fetch: Fetch,
  inputs?: Inputs,
): Promise<{ chosen: Chosen; request: SigningRequest | null; bytes: Uint8Array; h: AtrHash } | Declined>;

Reads the offer, chooses the option for account, fetches the ATR and compares its SHA-256 with the advertised hash. Only on a match does it build, with the hash it computed. request is what the signer is handed, or null when nothing is handed to the signer: the pairing has nothing for the buyer to sign, or the build is itself the payment, which finish completes with no signature. chosen.agreement is the agreement URL, for a pairing whose payment is not a public proof.

confirm and finish neither pay nor check the agreement; only transact and agree do. When chosen.agreement is set, the pairing's payment is not itself a public proof of H: do not sign yet. Call agree(bytes, chosen.agreement, signer, fetch), have your agent approve the approve it returns, call agree again with { approved }, and sign request only with its receipt in hand.

finishCopy Anchor Link

import type { AtrHash } from "@integraledger/lcp";
import type { Binding, Chosen, Declined, Presented, Signature, SigningRequest } from "@integraledger/terms";

declare function finish(
  bytes: Uint8Array,
  chosen: Chosen,
  signature: Signature,
  binding: Binding,
): Promise<{ signed: Presented; landed?: unknown; h: AtrHash } | { next: SigningRequest; h: AtrHash } | Declined>;

Rebuilds the payment from chosen and the bytes, joins the signer's answer, and returns the payment only when the pairing's bound reads the hash of these bytes from the completed payment. For a pairing signed in steps, returns next; call finish again with every answer so far, in order, as a list. For a pairing whose payment is not a public proof and whose bound finds no signed place for H, the proof is the agreement payment, and the completed payment is returned as it is. Where the signer moved the payment itself, a decline keeps it as moved. landed is a landed receipt the completion carried and the payment leaves out, as JSON, each integer a decimal string.

checkCopy Anchor Link

import type { AtrHash } from "@integraledger/lcp";
import type { Binding, Declined } from "@integraledger/terms";

declare function check(
  bytes: Uint8Array,
  presented: unknown,
  binding: Binding,
  landed?: unknown,
): Promise<{ h: AtrHash } | Declined>;

Confirms that the ATR hash the pairing reads from a payment held later is the SHA-256 of the kept bytes. A payment from which the pairing reads no ATR hash is declined signed-not-bound. Pass the landed receipt finish or transact returned beside the payment, where there is one, as landed: check holds it under the payment's own FETCHED member as bound reads it, and a landed member written into the payment is not read. The caller passes as landed only the receipt its own reader read for the payment, as finish or transact returned it, never a value another party sent. A landed of null is no receipt: the payment is read alone. A landed that is not a JSON object, or a payment that is not one, is declined signed-not-bound.

agreeCopy Anchor Link

import type { AgreeOptions, AgreementReceipt, Declined, Fetch, Signer, ToApprove } from "@integraledger/terms";

declare function agree(
  bytes: Uint8Array,
  url: string,
  signer: Signer,
  fetch: Fetch,
  options?: AgreeOptions,
): Promise<ToApprove | { receipt: AgreementReceipt } | Declined>;

The agreement for the hash of bytes at url, in two calls. Without options.approved, asks the agreement URL for its payment request and returns { approve, bytes, h }, signing nothing; where the agreement is already recorded, returns its receipt. With options.approved, the value of approve carried back unchanged, signs exactly that payment with signer, sends it, and returns the receipt once recorded. Before anything is fetched or signed, an approved payment whose required the protocol package's read refuses for its version, its legal context or agreement URL, or an accepts that is not a list of at most 32 entries holding an option is declined offer-unreadable with the read's code, as the unpaid request is, and one whose option is not one of required.accepts, compared by RFC 8785 form, is declined offer-unreadable with x402/option-not-in-document. The option paid is the first, in document order, that signer can pay with a pairing whose payment is itself a public proof. options.inputs are the buyer's own chain values; options.signal ends the exchange. Options holding anything but approved, inputs and signal, or a member of the wrong kind, and a signer whose account is not a string, are declined before any fetch. See agreement payments.

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. A 200 to the first, unpaid request is taken as an agreement already recorded.

Once the agreement payment is sent, a decline is agreement-pending with the payment as moved; it may settle yet. To collect the receipt, call again without approved: the gate asks the agreement URL unpaid and goes on once it answers 200 with the receipt, or declines agreement-pending again while it answers 202, signing nothing. Never call again with approved for the same agreement: every call with approved signs and sends a new agreement payment.

openChannelCopy Anchor Link

import type { Binding, ChannelHold, Declined, Presented } from "@integraledger/terms";

declare function openChannel(
  bytes: Uint8Array,
  opened: Presented,
  binding: Binding,
  landed?: unknown,
): Promise<ChannelHold | Declined>;

Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt transact returned beside it, where there is one. The caller passes as landed only the receipt its own reader read for the opening, as transact returned it, never a value another party sent. The opening must be of kind open, the pairing must read the hash of these bytes from it, and it must name its channel. The hold keeps the opening as signed and the read as its own landed member: the landed receipt, else the read the opening holds under its own FETCHED member.

withinCopy Anchor Link

import type { Binding, ChannelHold, Declined, Inputs, Presented, Signer } from "@integraledger/terms";

declare function within(
  doc: unknown,
  hold: ChannelHold,
  binding: Binding,
  signer: Signer,
  refund?: { amount?: string; paymentResponse?: { errorReason?: string } },
  inputs?: Inputs,
): Promise<{ signed: Presented; hold: ChannelHold } | Declined>;

Signs one later voucher, or a refund, in a held channel. The ATR's bytes, its hash and the channel come from the hold, and the amount from the new challenge. On x402's batch channels the challenge must advertise the held hash, and the payment the build returns must name the held channel before the signer is called. On an MPP session, a challenge that names another channel or another hash is declined before the signer is called, and one with no legal context is signed under the held hash. A voucher's cumulative amount is the recorded charge plus the option's amount; a refund's is the recorded charge. A Solana refund also carries the payer-signed request_close when it is taken again: when the errorReason of refund.paymentResponse, the settle failure's decoded PAYMENT-RESPONSE, read first, or else the document's error, is invalid_batch_settlement_svm_receiver_binding_unavailable. See channels and sessions.

recordChargeCopy Anchor Link

import type { ChannelHold, Declined } from "@integraledger/terms";

declare function recordCharge(hold: ChannelHold, chargedCumulativeAmount: string): ChannelHold | Declined;

Records the seller's cumulative charge: a decimal no lower than the charge last recorded and no higher than the largest amount signed in the channel.

TypesCopy Anchor Link

AtrHash and Json are exported by @integraledger/lcp; PaymentRequirements and PaymentRequired by @integraledger/lcp/x402.

Constants of the gateCopy Anchor Link