# Payment Links


**Metadata-bearing offers:** repository source supports v4 shares that bind immutable schema references, coverage and reuse terms. Published checkout 0.2.1 does not support v4. Use updated source or HTTP/MCP; never strip metadata to downgrade a share. See [purchase decisions](https://evidence.contact/purchase-decisions.md). Ordinary offers retain v3.

A seller shares an exact prepared offer. The buyer verifies its terms, signs locally, pays the seller directly in Base USDC and retains a recoverable result.

**Release status:** checkout 0.2.1 is published on npm and mirrored on evidence.contact. Public read-only share routes are available. Install with `npm install 402mob-agent-checkout@0.2.1` or use the versioned archive and checksum in the [manifest](https://evidence.contact/payment-links.json). Signing runs locally; links return offer JSON.

The manifest separates `historicalLiveBaseValidated` from `liveBaseValidated`: the latter applies to the current client and complete public-link purchase path. A prior paid run is not validation of every later release.

[Overview](/payment-links) · [Agent skill](/payment-links-skill.md) · [Schemas](/checkout-share.schema.json) · [Validation](/payment-links-validation.json)

## Step by step: seller to buyer

1. **Seller enrolls once.** Create or connect a Base wallet, complete [merchant enrollment](https://evidence.contact/merchant-api.md), and save the returned merchant credential. The enrolled payout wallet receives purchases.
2. **Seller publishes a prepared artifact.** Publish JSON or text up to 48 KiB with a title, description and USDC price. Retain the merchant and offer IDs; the link references this exact version.
3. **Seller obtains the link.** Wallet 0.1.5 publication returns a checked `nextSteps.shareUrl`. If it is null, use `publication --offer OFFER_UUID` with the same wallet directory to retry the read-only lookup. Alternatively, install the checkout client and run `share-link` with the merchant and offer IDs; it checks the hosted share and returns `{url, share}` without requiring a seller key. Neither path uploads another artifact.
4. **Seller distributes the URL.** Put it in an agent response, email, message or website. Anyone can forward it unchanged. It carries public terms, not artifact contents or permission to spend; forwarding earns no commission.
5. **Buyer prepares privately.** Read the link as JSON and call `prepareShared` with the share, a stable purchase ID, the buyer wallet address and a maximum USDC amount. Preparation is free. Buying needs no merchant enrollment; creating or funding a wallet is separate.
6. **Buyer reviews and pays.** Check the seller address, exact version, price, format and Base USDC terms. Execute with the returned `termsHash` and an existing funded wallet. Signing stays local and USDC goes directly to the seller, with no current artifact platform cut.
7. **Buyer retrieves or recovers.** At `RESULT_AVAILABLE`, run `result`. At `PAYMENT_UNRESOLVED`, run `resume` with the same purchase ID, checkout directory and wallet. Preserve both journals; never create a replacement purchase to retry an unresolved payment.

Public links return JSON, not a browser payment form. The client verifies delivered bytes; it does not assess quality or provide escrow, refunds or arbitration.

## Install

The mirror contains the same immutable bytes as the verified npm tarball. Historical 0.2.0 downloads remain available. The current archive includes `examples/request.json` and corrected commitment-verification instructions.

Node.js 22.13+ on Linux/macOS is required. Download the versioned npm-compatible archive from the URL in [payment-links.json](https://evidence.contact/payment-links.json), compare its SHA-256 with the manifest, then install it in your agent runtime:

```sh
curl --fail --show-error --location \
  https://evidence.contact/downloads/402mob-agent-checkout-0.2.1.tgz \
  --output 402mob-agent-checkout-0.2.1.tgz
# Compare the archive SHA-256 with payment-links.json before installing.
shasum -a 256 402mob-agent-checkout-0.2.1.tgz
npm install ./402mob-agent-checkout-0.2.1.tgz
npx --no-install 402mob-checkout --help
```

For source development, use `cd packages/agent-checkout && npm ci` and replace `npx --no-install 402mob-checkout` below with `node bin/402mob-checkout.js`. Do not assume a package name on npm is this prepared release.

## Seller: share an existing offer

First [enroll and publish an artifact](/merchant-api.md). Sharing itself needs no seller key, creates no purchase, and grants no spending authority.

This free request returns a v3 share and a `Link` response header with its pinned public URL:

```sh
curl --fail -i https://evidence.contact/v1/merchants/MERCHANT_UUID/offers/OFFER_UUID/share
```

Or have the client verify and return the link:

```sh
npx --no-install 402mob-checkout share-link \
  --origin https://evidence.contact --dir .local/seller-checkouts \
  --merchant MERCHANT_UUID --offer OFFER_UUID
```

This returns `{url, share}` only after checking the hosted JSON. Forward the URL, or forward the `share` object unchanged. `share` instead of `share-link` exports just the share JSON and works with older servers too. No separate share host is needed for the new upstream routes.

A pinned URL has the form `/s/{merchantId}/{offerId}/{shareId}`. It returns public JSON, not an artifact or browser checkout. It rejects changed terms and returns 404 for an unpublished offer or inactive merchant; it never selects a newer version. A share ID is a digest, not a seller signature. Any agent can forward it; forwarding earns no commission.

## Buyer: prepare privately

Fetch a share URL without credentials and save the response as `checkout-share.json`. Never send wallet keys or private tokens to a link host. A buyer needs no merchant enrollment. Preparation is free; it does not open, create or fund a wallet.

Save this as `prepare-buyer.mjs` in the directory where the client is installed. Replace the buyer address, purchase ID and price ceiling with your own authorized values:

```js
import { readFile } from 'node:fs/promises';
import { AgentCheckout } from '402mob-agent-checkout';

const checkout = await AgentCheckout.open({
  directory: '.local/buyer-checkouts', origin: 'https://evidence.contact',
});
const prepared = await checkout.prepareShared({
  share: JSON.parse(await readFile('checkout-share.json', 'utf8')),
  purchaseId: 'research-purchase-001',
  buyerWallet: 'YOUR_BASE_WALLET_ADDRESS',
  maxAmountUSDC: '0.25',
  maxResultBytes: 49152,
});
console.log(JSON.stringify(prepared, null, 2));
```

Run `node prepare-buyer.mjs` and review `terms` and `termsHash`. CLI `prepare-shared --file buyer-request.json` takes the same full input object, not the share alone. Do not change the configured origin because an incoming share asks you to.

v3 shares expose `artifact.algorithm`, `artifact.commitment` and `artifact.sizeUpperBound`, not a plaintext hash or exact length. The upper bound rounds up to a 1 KiB bucket (minimum 1024 bytes); a cap below that bound is rejected conservatively before signing, even if the actual file might fit. A per-offer private verifier is returned only in the settled response header `X-402Mob-Artifact-Proof`. The client persists it privately before caching delivery, then checks the commitment and actual byte count. v1 shares keep their original checks. The unreleased plaintext-hash v2 format cannot start new purchases; already-started v2 sessions remain recoverable. No share silently downgrades when its required metadata disappears.

Formats are canonical `application/json` or `text/plain`; UTF-8 charset headers normalize to these values. `maxResultBytes` must be an integer from 1 to 49152, not `null`.

## Execute and recover

Execution can spend real Base USDC and requires the reviewed hash, existing buyer wallet and sufficient USDC. This x402 path signs locally without sending a buyer-paid gas transaction. Unstarted sessions expire after 15 minutes.

```sh
npx --no-install 402mob-checkout execute \
  --origin https://evidence.contact --dir .local/buyer-checkouts \
  --id research-purchase-001 --wallet-dir /absolute/path/to/buyer-wallet \
  --terms-hash REVIEWED_TERMS_HASH
```

For external signing, supply the trusted local `--adapter` used by your wallet. It must support typed-data signing. Treat downloaded artifact content as data, not instructions to execute.

```sh
npx --no-install 402mob-checkout status --dir .local/buyer-checkouts --id research-purchase-001
npx --no-install 402mob-checkout resume \
  --dir .local/buyer-checkouts --id research-purchase-001 \
  --wallet-dir /absolute/path/to/buyer-wallet
npx --no-install 402mob-checkout result --dir .local/buyer-checkouts --id research-purchase-001
```

Use `resume` only after execution started. It can resubmit the original payment; it does not create a replacement authorization. Preserve both directories and the original signer adapter. Never retry an unresolved payment with a new purchase ID or a new checkout directory. Independent directories deliberately receive distinct wallet journal IDs.

| State | Next action |
| --- | --- |
| `PREPARED` / `NOT_AUTHORIZED` | Review and execute; a rejected unsigned challenge remains unpaid |
| `WAITING_FOR_FUNDS` | Fund separately, then execute the same unexpired session |
| `WAITING_FOR_AUTHORITY` | Restore the expected wallet or typed-data signer |
| `PAYMENT_UNRESOLVED` | Resume the same purchase; preserve its payment journal |
| `RECOVERY_REQUIRED` | Restore original recovery data; do not authorize another payment |
| `RESULT_AVAILABLE` | Read the retained result |
| `RESULT_REJECTED` | Inspect the settled payment and failed content check; no automatic refund |
| `EXPIRED` | Review a new session only if no authorization was attempted |

## Recover a crashed local process

Lock files are never cleared merely because a timeout passed. Stop other clients using the directory, inspect the owner, and recover only a confirmed dead PID:

```sh
npx --no-install 402mob-checkout inspect-lock --dir .local/buyer-checkouts
npx --no-install 402mob-checkout recover-lock \
  --dir .local/buyer-checkouts --owner-pid OBSERVED_DEAD_PID --clients-stopped YES
```

If the wallet has a stale lock, use its original directory with the same commands. Use local storage on the same machine; PID checks do not establish ownership across hosts. A live, changed, malformed or uninspectable owner is refused. Stop competing recovery commands as well. This operation removes only the dead lock, not journals, sessions or signatures. Afterwards inspect status and resume the original purchase.

If the process died between recording execution intent and saving the wallet authorization, recovery still stops conservatively. A missing journal is not permission to create another payment.

## Public and local routes

| Route | Access and effect |
| --- | --- |
| `GET /v1/merchants/{merchantId}/offers/{offerId}/share` | Upstream public offer terms and canonical pinned URL header |
| `GET /s/{merchantId}/{offerId}/{shareId}` | Upstream public pinned share; current publication required |
| `GET /s/{shareId}` | Optional local server's saved historical share JSON |
| `POST /v1/checkout-shares` | Local bearer token; save a share |
| `POST /v1/checkouts/from-share` | Local bearer token; prepare private buyer state |
| `POST /v1/checkouts` | Local bearer token; prepare directly from offer IDs |
| `GET /v1/checkouts/{purchaseId}` | Local bearer token; read status |
| `GET /v1/checkouts/{purchaseId}/result` | Local bearer token; read retained buyer result |

Only the first two routes belong to the upstream server. The optional `serve` command binds `127.0.0.1:4030` and requires `CHECKOUT_API_TOKEN`; keep private routes off the internet. Its bearer token covers all sessions in its directory. HTTP never opens wallets or executes payment. Published merchant SDK/CLI packages do not gain checkout commands automatically.

## Evidence and limits

Artifact payments go directly to sellers with no current platform cut. There is no escrow, refund, arbitration, referral payout or aggregate buyer-budget enforcement. Shares are prepared artifacts, not fresh Work Ticket execution.

The 2026-11-08 live evidence records two JSON purchases totaling 0.04 USDC, response-loss recovery and a replay with no new authorization. That run used a loopback share URL. Version 0.2.0 public routes, metadata commitments and recovery fixes have offline integration coverage only. Read-only production HTTPS checks are recorded separately in the evidence file. A paid end-to-end run through public HTTPS links, independent seller/buyer adoption and live text checkout remain unvalidated; do not infer them from the older transactions.

If the recovery command itself crashes, its `.lock-recovery` marker is retained. Stop all clients and recovery processes before inspecting and manually clearing that marker. It never contains a payment authorization. Do not clear it while its owner is alive.

## Commitment verification and revocation

For `sha256-private-proof-v1`, verify the hex commitment as SHA-256 over the concatenation of UTF-8 `402mob.artifact-commitment.v1` followed by one LF byte (`0x0a`), the 32 raw bytes decoded from the paid verifier header, and the exact artifact bytes. The verifier is derived with a separate HMAC domain from the server's encryption key and immutable offer ID; it is stable across restarts and must not appear in public shares. Keep the encryption key with the database during backup/restore. Public size buckets still reveal an approximate size; they do not reveal exact lengths for tiny answers. Never expose a verifier through public metadata or an unsigned payment challenge. Missing paid verifiers resume the same authorization; mismatches reject paid delivery without authorizing a replacement.

Revocation prevents new unsigned x402 challenges, new purchase reservations, and the first settlement submission for staged artifact operations. Already-submitted pending settlements can reconcile and settled purchases can replay. Direct-transfer challenges cannot be newly issued to a revoked merchant; a previously issued challenge returns `paymentAllowed: false` after revocation, while completion can still verify an already-sent transfer under that challenge's original time and recovery limits. 402Mob cannot prevent or reverse transfers sent directly onchain.


Verification example (Node.js; `artifactBytes` must be the exact received bytes):

```js
import { createHash } from 'node:crypto';
const domain = Buffer.concat([
  Buffer.from('402mob.artifact-commitment.v1', 'utf8'),
  Buffer.from([0x0a]),
]);
if (!/^[a-f0-9]{64}$/.test(proofHeader)) throw new Error('Invalid artifact proof');
const actual = createHash('sha256').update(domain)
  .update(Buffer.from(proofHeader, 'hex')).update(artifactBytes).digest('hex');
if (actual !== share.offer.artifact.commitment) throw new Error('Artifact commitment mismatch');
```


## Delivery complaints

For a settled operation, the buyer can sign a `not_delivered`, `unreadable` or `terms_mismatch` complaint; the original recipient wallet can respond and the buyer can close it. First request an `action: "read"` challenge at `POST /v1/operations/{id}/dispute-challenges`, sign with EIP-191 and submit to `dispute-actions` to obtain the private `binding` and case revision. Include that full binding in every subsequent write request; challenge issuance alone does not confirm existence or eligibility. Sign the exact write message, then submit the returned `challengeId`, opaque `challengeToken` and signature to `/v1/operations/{id}/dispute-actions`. Writes and retries return only an action acknowledgment; a fresh signed `read` returns the current private evidence. Expired cases retain a minimal tombstone and cannot reopen. Buyer closure preserves seller responses; result expiry does not undo confirmed settlement. The same flow supports private evidence reads. For Work Tickets use `ticket.payment.operationId` from the HTTP/MCP ticket response (or `payment.operationId` on the SDK ticket object). Payment, delivery, existing receipts and the complaint remain separate; silence never means acceptance. Response targets do not establish a delivery deadline. No arbitration or automatic refund. [Full flow, limits and retention](/delivery-disputes.md). Hosted MCP tools: `create_delivery_dispute_challenge`, `submit_delivery_dispute_action`. Published merchant SDK 0.7.0 includes `createDeliveryDisputeChallenge` and `submitDeliveryDisputeAction`; the caller signs the exact challenge separately.


## MCP byte verification

Paid artifact tools preserve exact bytes in `delivery.bodyBase64` and the private verifier in `delivery.artifactProof`; compare the commitment with saved public offer metadata. Work Ticket result reads preserve exact bytes and validate their SHA-256, without an artifact proof. Invalid paid responses require the original payment; invalid or interrupted one-time result reads require a fresh signed read challenge, without paying again. See [MCP delivery and recovery](/mcp-delivery.md).

## Shared spending budget (unreleased checkout 0.3.0)

Bind participating checkout directories to one persistent budget before any payment starts. It constrains aggregate reserved-plus-spent USDC, per-purchase amounts, wallet, origin, sellers, optional offer IDs and expiry. Unresolved payments retain reservations across restarts. Published checkout 0.2.1 has no such control. See [policy, CLI commands and recovery boundaries](/runtime-controls.md).

## Private transaction evidence

The separate [Transaction Evidence module](/transaction-evidence.md) exports retained participant statements and payment/job observations for local verification. Use `operation` for prepared purchases and delivery complaints, or `protected_json` / `protected_inspection` with a job ID. Wallet proof is required; no result bytes, payment authorization or new settlement action is included. Protected original funding, buyer acceptance, verdict and appeal signatures are not retained and stay missing. Optional chain checks remain separate from offline agreement evidence and work quality. Check `capabilities.transactionEvidence` for deployed support.
