x402

What this skill does

# x402 Payment Reference

Handle `402 Payment Required` HTTP responses by executing payment and fetching the protected resource.

## When to Use

- The user wants to access a resource that returns **HTTP 402 Payment Required** with a `PAYMENT-REQUIRED` header — either known in advance or discovered by a previous attempt.
- Do not pre-fetch the resource yourself to "check" — phase 1 of the script does the fetch.

## Script

### buildX402Payment.js

**Command (phase 1 — discover)**: `node scripts/buildX402Payment.js --resource <url> [--did <did>]`
**Command (phase 2 — execute)**: `node scripts/buildX402Payment.js --paymentRequiredFilePath <path> --paymentHash <hash> [--did <did>]`
**Hint**: **NEVER reuse or cache a previous response from this script.** Every invocation produces unique, time-sensitive output (nonces, signatures, payment tokens). Always execute the script again to get a fresh result — even if the arguments are identical to a prior call.

Executes the x402 payment flow in two strictly separated phases.

- **Phase 1** (`--resource` only): the script fetches the resource, expects a `402` response with a `PAYMENT-REQUIRED` header, caches the decoded challenge to a temp file named by its SHA-256 hash, and returns the available payment options together with the cached file path. It never signs a payment.
- **Phase 2** (`--paymentRequiredFilePath` + `--paymentHash`): the script reads the cached challenge file, looks up the chosen payment option by its `--paymentHash`, signs the payment, sends the `PAYMENT-SIGNATURE` header to the resource, and returns the result.

- `--resource` — (phase 1 only) The URL of the protected resource. The script fetches it and expects HTTP 402 with a `PAYMENT-REQUIRED` header. If the response is any other status, or the header is missing, the script returns status `failed`. Cannot be combined with `--paymentRequiredFilePath` or `--paymentHash`.
- `--paymentRequiredFilePath` — (phase 2 only) Absolute path to the cached payment-required JSON file returned by phase 1. Must be combined with `--paymentHash`. Mutually exclusive with `--resource`.
- `--paymentHash` — (phase 2 only, required) The SHA-256 hash of the chosen payment option from phase 1. Always required on phase 2, even when only one option was offered. Cannot be passed with `--resource`.
- `--did` — (optional) The DID of the signer. Omit unless the user has explicitly asked to pay from a specific DID — the script falls back to the default DID from `getIdentities.js`, which is correct for normal use. Do not prompt the user for a DID on your own.

You **must** pick exactly one phase per invocation. Passing `--resource` together with `--paymentHash` (or with `--paymentRequiredFilePath`) is rejected.

---

## Output

The script always outputs JSON to stdout with a top-level `status` of `success`, `failed`, or `input_required`. See [Handling output](#handling-output) below for the action to take on each.

---

## Workflow

### 1. Trigger

Use this skill whenever the user wants to access a resource you know (or strongly suspect) is gated by `402 Payment Required` with a `PAYMENT-REQUIRED` header.

**Do not fetch the resource yourself first.** `buildX402Payment.js` performs the HTTP request in phase 1, parses the header, and caches the challenge — making your own fetch beforehand is wasted work and may consume a one-shot challenge.

### 2. Ensure identity exists

Run `node scripts/getIdentities.js`. If no identity is configured, create one first (see `reference/identity/SKILL.md`).

### 3. First call — discover payment options (phase 1)

```bash
node scripts/buildX402Payment.js \
  --resource 'https://api.example.com/weather'
```

The script fetches the URL, decodes the `PAYMENT-REQUIRED` header, caches it to a temp file, and **never signs a payment on the first call**. Even when only one option is offered, it returns the list and waits for the user to confirm by selecting a `paymentHash`.

The script outputs `status: "input_required"` with three top-level fields in `data`:

- `resource` — describes the protected resource the user is paying for:
  - `resource.url` — the URL of the protected resource.
  - `resource.description` — a human-readable description of what the resource provides.
- `paymentOptions` — the list of payment options. Each option includes:
  - `hash` — the payment hash (use as `--paymentHash` in the next call)
  - `amount` — the payment amount
  - `asset` — the asset name (e.g., "USDC") or contract address
  - `network` — the network identifier (e.g., "eip155:84532")
  - `requiredAttestations` — informational list of attestation schema IDs that this payment type requires in general; may be non-empty even when the user already holds all of them — **do not use this field to decide whether to block the payment**
  - `hasAllAttestations` — `true` if the user already holds every required attestation and the payment can proceed; `false` if some are missing
  - `attestationLinks` — verification URLs the user must complete to obtain **missing** attestations; empty when `hasAllAttestations` is `true`
- `paymentRequiredFilePath` — absolute path to the cached challenge file. Pass this back via `--paymentRequiredFilePath` on the second call. The file lives in the OS temp directory and is named by the SHA-256 hash of the full challenge content.

**Present the options to the user.** Always start by showing `resource.url` and `resource.description` so the user knows **what** they are paying for. Then show each payment option's amount, asset, network, and whether attestations are required. Ask the user to choose one payment option or decline payment.

If the user declines, do **not** run phase 2. Report that the resource is unavailable without payment and stop.

> **CRITICAL: Formatting `amount` for display (UI only)**
>
> The `amount` field is a raw on-chain integer in the asset's smallest unit. **Never show it to the user as-is** — always convert to a human-readable price by dividing by `10^decimals`, where `decimals` depends on the asset **and the network**.
>
> | Asset       | Network                                          | Decimals | Divisor              |
> | ----------- | ------------------------------------------------ | -------- | -------------------- |
> | USDC / EURC | Ethereum, Polygon, Arbitrum, Optimism, Base      | 6        | 10⁶ = 1 000 000      |
> | USDT        | Ethereum, Polygon, Arbitrum                      | 6        | 10⁶ = 1 000 000      |
> | USDT        | BNB Smart Chain (BEP-20)                         | 18       | 10¹⁸                 |
>
> Examples:
> - `amount: "1000000"` USDC on Base → **$1.00** (or €1.00 for EURC)
> - `amount: "1000000000000000000"` USDT on BNB Smart Chain → **$1.00**
>
> This conversion is **for UI/presentation only**. Always pass the original raw `hash` value back to phase 2 via `--paymentHash` — never round, scale, or modify any field you forward to the script.

> **CRITICAL: Reading attestation status**
>
> Use only `hasAllAttestations` + `attestationLinks` to decide whether a payment is blocked. **Never use `requiredAttestations` alone** — it lists schema IDs informationally and can be non-empty even when the user already holds everything.
>
> | `hasAllAttestations` | `attestationLinks` | What it means                                                       |
> | -------------------- | ------------------ | ------------------------------------------------------------------- |
> | `true`               | empty              | User holds all attestations — payment can proceed immediately.      |
> | `false`              | non-empty          | User is missing attestations — show every link as-is and wait.      |
>
> When `attestationLinks` is non-empty: show every link verbatim, do not open/resolve them yourself, do not complete attestations on the user's behalf, and do not hide options that require attestations.

### 4. Second call — execute chosen payment (phase 2)

This step is **always required** — there is