@integraledger/terms
Generated from the TypeScript source by TypeDoc.
Interfaces
AgreementPayment
The agreement payment, for the buyer's agent to approve before anything is signed: the agreement URL; option, the
option of the agreement URL's payment request that the gate pays, whose amount, asset, payTo and network are
the terms the agent approves; and required, that payment request as the agreement URL served it.
Properties
option
readonly option: PaymentRequirements;required
readonly required: PaymentRequired;url
readonly url: string;AgreementReceipt
The agreement resource's answer once the agreement payment carrying the ATR hash is recorded.
Properties
agreed
agreed: true;atrHash
atrHash: `0x${string}`;network
network: string;transaction
transaction: string;AgreeOptions
agree's optional members: the agreement payment the agent approved, exactly as it was returned in approve; the
buyer's own chain values; and a signal that ends the exchange.
Properties
approved?
readonly optional approved?: AgreementPayment;inputs?
readonly optional inputs?: Inputs;signal?
readonly optional signal?: AbortSignal;ChannelHold
A channel the buyer opened for an ATR it compared, as JSON the caller keeps and hands back.
Properties
atr
atr: string;Padded standard base64 of the ATR bytes the opening compared, in its canonical form (RFC 4648 sections 3.5, 4).
channel
channel: string;charged
charged: string;The server's cumulative charge last recorded, decimal; "0" at the opening.
h
h: `0x${string}`;landed?
optional landed?: Json;The read made for the opening, as a JSON object: the landed receipt openChannel took, else the read the opening
held under its own FETCHED member (@integraledger/lcp's symbol, which no wire form carries), each bigint as its
decimal string. Absent when there is neither. within holds it under the opening's own FETCHED member, as
bound reads it.
network
network: string;opening
opening: Json;The signed opening payment as the gate returned it, written as plain JSON: its own members, as signed. A member of
its own, landed or any other, is never read as the read made for the opening.
pairing
pairing: string;signedMax
signedMax: string;The largest maxClaimableAmount signed in this channel, decimal.
Chosen
What the gate chose to pay, as plain JSON data, so finish can rebuild the same request. agreement is the agreement
URL the seller's offer names, for a pairing whose payment is not itself a public proof of the ATR hash.
Properties
agreement?
optional agreement?: string;choice
choice: Json;pairing
pairing: string;ref
ref: string;Reason
Properties
code
readonly code: DeclineCode;detail
readonly detail: string;Signer
Properties
account
readonly account: string;The payer, CAIP-10: eip155:84532:0xf39F…2266.
Methods
sign()
sign(request): Promise<Json>;Signs exactly request.
Parameters
request
Returns
Promise<Json>
ToApprove
An agreement payment the agent approves before it is signed, with the ATR bytes the gate compared and their hash.
Properties
approve
readonly approve: AgreementPayment;bytes
readonly bytes: Uint8Array;h
readonly h: `0x${string}`;TransactOptions
transact's optional members: the buyer's own chain values; the signer that pays the agreement; the agreement payment
the agent approved, exactly as transact or agree returned it in approve; and a signal that ends the agreement
exchange.
Properties
agreementSigner?
readonly optional agreementSigner?: Signer;approved?
readonly optional approved?: AgreementPayment;inputs?
readonly optional inputs?: Inputs;signal?
readonly optional signal?: AbortSignal;Type Aliases
Binding
type Binding = LcpBinding | typeof MPP_BINDINGS[number];The pairing the caller names, as its binding.
DeclineCode
type DeclineCode =
| "pairing-not-supported"
| "offer-unreadable"
| "no-payable-option"
| "link-not-https"
| "atr-unfetchable"
| "atr-too-large"
| "hash-mismatch"
| "signer-failed"
| "signed-not-bound"
| "agreement-not-offered"
| "agreement-pending"
| "agreement-failed";Declined
type Declined = object;A decline. moved is present when the signer moved the payment before the decline: the payment as signed, in the
protocol's own form, with the ATR bytes and their hash, for the buyer to keep and present again.
Properties
decline
readonly decline: Reason;moved?
readonly optional moved?: object;bytes
readonly bytes: Uint8Array;h
readonly h: AtrHash;signed
readonly signed: unknown;Fetch
type Fetch = (url, init) => Promise<Response>;WHATWG fetch, or anything with its call shape. The caller's network policy (proxy, egress rules) lives here. The gate
asks with redirect: "manual" and reads a 3xx answer, or one of type opaqueredirect, as a redirect it does not
follow.
Parameters
url
string
init
headers?
Record<string, string>
method
"GET"
redirect
"manual"
signal
AbortSignal
Returns
Promise<Response>
Inputs
type Inputs = object;The buyer's own values a pairing's build needs beside the offer, such as a recent block or an account nonce.
Index Signature
[k: string]: JsonPresented
type Presented = LcpPresented | MppCredential;What the buyer presents as payment.
Signature
type Signature = Json;The signer's answer, as JSON. Each kind's form is its buyer piece's: a signature for the kinds whose payment takes one
signature, an object for the kinds whose payment takes several values, and a list, in order, for batch. Byte strings
are 0x hex, except where the signers guide names another form for the kind: base58, base64, or hex digits without
0x.
SigningRequest
type SigningRequest =
| Extract<X402Unsigned, unknown>["request"]
| Extract<MppUnsigned, unknown>["request"]
| UsdcUnsigned["request"]
| SessionUnsigned["funding"]
| RailSessionUnsigned["request"]
| KeyAuthorizationUnsigned["request"]
| SvmUnsigned["request"]
| StellarUnsigned["request"]
| XrplUnsigned<unknown>["request"]
| HederaUnsigned["request"]
| Extract<Awaited<ReturnType<typeof exactHederaExecutor["build"]>>, {
request: unknown;
}>["request"]
| AvmUnsigned["request"]
| AptosUnsigned["request"]
| CardanoUnsigned["request"]
| SuiUnsigned["request"]
| StarknetUnsigned["request"]
| PolkadotUnsigned["request"]
| TronUnsigned["request"]
| TvmUnsigned["request"]
| NearUnsigned["request"]
| CasperUnsigned["request"]
| CcdUnsigned["request"]
| LnUnsigned["request"]
| object & TapUnsigned
| object & ViUnsigned
| {
content: Ap2Unsigned["content"];
kind: "ap2-checkout-mandate";
}
| {
checkout: UcpUnsigned["checkout"];
kind: "ucp-checkout";
}
| {
allowance: AcpUnsigned["allowance"];
kind: "acp-allowance";
}
| {
kind: "batch";
requests: readonly (BatchRequest | WithinSigningRequest)[];
}
| Extract<BatchRequest, {
kind: "ed25519-raw";
}>;What a signer is handed: the request of the pairing's build result, exactly as built, one kind per signing
scheme. The protocol-group results that carry no kind of their own are tagged here: the TAP field (tap-field), VI's
checkout mandate (vi-checkout-mandate), AP2's checkout-mandate content (ap2-checkout-mandate), the UCP checkout
for the buyer's mandate issuer (ucp-checkout) and ACP's allowance (acp-allowance). batch is several requests,
signed in order, as are the requests of an in-channel payment. ed25519-raw is raw Ed25519 over the bytes given.
tempo-calls is a Tempo charge with splits: the calls, in order, of one 0x76 transaction.
Functions
agree()
function agree(
bytes,
url,
signer,
fetch,
options?
): Promise<
| Declined
| ToApprove
| {
receipt: AgreementReceipt;
}>;Without approved: asks the agreement URL for its challenge and returns the agreement payment to approve, signing
nothing, or the receipt where the agreement is already recorded. With approved: signs exactly that payment with
signer, sends it to url, and returns the receipt once recorded; a payment whose challenge the protocol package's
read refuses for a fault of its own (its version, legal context or agreement URL, or an accepts that is not a list
of at most 32 entries holding an object) is declined as the unpaid request declines that challenge, and one whose
option is not one of that challenge's accepts, by RFC 8785 form, is declined offer-unreadable with
x402/option-not-in-document, each before any fetch or signer call.
bytes are the ATR the gate compared, whose hash the agreement payment carries; inputs are the buyer's own chain
values; signal ends the exchange. Options holding anything but approved, inputs and signal, a signal that
is not an AbortSignal, an approved that is not of the agreement payment's form, inputs that is not an object,
or a signer whose account is not a string, is declined no-payable-option with x402/input-malformed before any
fetch or signer call. A url that is not an https URL is declined link-not-https with x402/link-not-https for an
absolute URL of another scheme and x402/legal-context-malformed for any other value, before any fetch.
Parameters
bytes
Uint8Array
url
string
signer
fetch
options?
Returns
Promise<
| Declined
| ToApprove
| {
receipt: AgreementReceipt;
}>
check()
function check(
bytes,
presented,
binding,
landed?
): Promise<
| Declined
| {
h: `0x${string}`;
}>;Confirms that the ATR hash the pairing reads from a payment held later is the SHA-256 of the kept bytes, with the
landed receipt finish or transact returned beside the payment, where it returned one, held under the payment's
own FETCHED member as bound reads it. 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, as without one. A payment from which the pairing reads no ATR hash is declined
signed-not-bound, as is a landed receipt that is not a JSON object beside a payment that is one. A landed
member of the payment's own is not read.
Parameters
bytes
Uint8Array
presented
unknown
binding
landed?
unknown
Returns
Promise<
| Declined
| {
h: `0x${string}`;
}>
confirm()
function confirm(
doc,
binding,
account,
fetch,
inputs?
): Promise<
| Declined
| {
bytes: Uint8Array;
chosen: Chosen;
h: `0x${string}`;
request: SigningRequest | null;
}>;Reads the offer, chooses the option, 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. For a pairing whose payment is not itself a public proof, chosen.agreement is
the agreement URL the offer names. inputs that is not an object is declined no-payable-option with
<namespace>/input-malformed before the offer is read.
Parameters
doc
unknown
binding
account
string
fetch
inputs?
Inputs = {}
Returns
Promise<
| Declined
| {
bytes: Uint8Array;
chosen: Chosen;
h: `0x${string}`;
request: SigningRequest | null;
}>
finish()
function finish(
bytes,
chosen,
signature,
binding
): Promise<
| Declined
| {
h: `0x${string}`;
landed?: unknown;
signed: Presented;
}
| {
h: `0x${string}`;
next: SigningRequest;
}>;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 whose payment is not a
public proof and whose bound finds no signed place for the hash, 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.
Where the completion carried the landed receipt bound reads and the payment sent leaves it out, landed is
returned beside the payment as JSON, each integer a decimal string, so check and openChannel can later read the
payment with it.
Parameters
bytes
Uint8Array
chosen
signature
Json
binding
Returns
Promise<
| Declined
| {
h: `0x${string}`;
landed?: unknown;
signed: Presented;
}
| {
h: `0x${string}`;
next: SigningRequest;
}>
openChannel()
function openChannel(
bytes,
opened,
binding,
landed?
): Promise<Declined | ChannelHold>;Takes a channel pairing's signed opening and the ATR bytes the gate compared for it, with the landed receipt
transact returned beside the opening, where it returned 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, with that
receipt held under its own FETCHED member, 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 all three together. Without landed, an opening that holds its
read under its own FETCHED member, as @integraledger/lcp's fetchPresented returns it, is read with that read,
and the hold keeps it. The hold keeps the opening as signed, and the read as its own landed member; a member of the
opening's own, landed or any other, is never read as the read.
Parameters
bytes
Uint8Array
opened
binding
landed?
unknown
Returns
Promise<Declined | ChannelHold>
recordCharge()
function recordCharge(hold, chargedCumulativeAmount): Declined | ChannelHold;Records the server's cumulative charge for the channel. It must be a decimal no lower than the charge last recorded and no higher than the largest amount signed in the channel.
Parameters
hold
chargedCumulativeAmount
string
Returns
transact()
function transact(
doc,
binding,
signer,
fetch,
options?
): Promise<
| Declined
| ToApprove
| {
agreement?: AgreementReceipt;
bytes: Uint8Array;
h: `0x${string}`;
landed?: unknown;
signed: Presented;
}>;confirm, then, for a pairing whose payment is not itself a public proof, the agreement, then the signer, then
finish. Without approved, an agreement not yet recorded is returned as approve, the agreement payment for the
agent to approve, and nothing is signed; with approved, that payment is signed and paid, and the resource's payment
is signed only with the agreement's receipt in hand. On a decline before the signer the signer is never called. Where
the build is itself the payment the signer is not called; where the pairing has nothing for the buyer to sign,
signed is null after the comparison. agreement is the agreement's receipt, where the pairing needs one. landed
is finish's, where it gives one. signal ends the agreement exchange. Options holding anything but inputs,
agreementSigner, approved and signal, or a signer or agreement signer whose account is not a string, are
declined no-payable-option with <namespace>/input-malformed before any fetch or signer call.
Parameters
doc
unknown
binding
signer
fetch
options?
Returns
Promise<
| Declined
| ToApprove
| {
agreement?: AgreementReceipt;
bytes: Uint8Array;
h: `0x${string}`;
landed?: unknown;
signed: Presented;
}>
within()
function within(
doc,
hold,
binding,
signer,
refund?,
inputs?
): Promise<
| Declined
| {
hold: ChannelHold;
signed: Presented;
}>;Signs one later voucher, or a refund, in a held channel. The ATR bytes, the opening's hash and the opening's
channel are re-derived from the hold. An x402 challenge must advertise the held hash. An MPP session's challenge
that names another channel or another hash is declined, and one with no legal context is signed under the held
hash. A voucher's maxClaimableAmount is the recorded charge plus the option's amount; a refund's is the recorded
charge. inputs are the buyer's own chain values a refund's build takes; inputs that is not an object is declined
no-payable-option with <namespace>/input-malformed.
A Solana refund is the voucher alone. Taken again after the receiver's binding is unavailable, it also carries the
payer-signed request_close, built with the recentBlockhash, computeUnitLimit and computeUnitPrice of
inputs: when the errorReason of refund.paymentResponse, the settle failure's decoded PAYMENT-RESPONSE, read
first, or else the challenge's error, is invalid_batch_settlement_svm_receiver_binding_unavailable. A Solana
refund value given in another form, or a paymentResponse that is not an object or whose errorReason is not a
string, is declined no-payable-option with x402/input-malformed, and the refund taken again without a
recentBlockhash with x402/input-missing. No other pairing's refund reads these values or this code.
On x402's batch channels, the channel the built payment would name must be the held one before the signer is called. On MPP's sessions, a channel the challenge names must be the held one and a legal context, where present, must name the held hash, before the signer is called, and the voucher is built from the held opening. In both, the signed payment must then be of the expected kind, commit to the held hash where the pairing's voucher carries one, and name the held channel, or it is dropped.
Parameters
doc
unknown
hold
binding
signer
refund?
amount?
string
paymentResponse?
{
errorReason?: string;
}
paymentResponse.errorReason?
string
inputs?
Inputs = {}
Returns
Promise<
| Declined
| {
hold: ChannelHold;
signed: Presented;
}>