/pay-with-app

name: pay-with-app
description: >
  Pay HTTP 402 payment challenges issued by OKX's Agent Payments Protocol
  (APP) on X Layer using tokens from any chain via the Uniswap Trading API.
  Use this skill whenever the user encounters a 402 challenge whose network
  resolves to X Layer (chain 196), mentions "APP", "Agent Payments
  Protocol", "OKX agent payment", "OKX Onchain OS", "OKX agentic wallet",
  "x402 on X Layer", "USDT0", "x42", "Instant Payment", "Batch Payment",
  "pay for X Layer API", or wants to pay an OKX-backed merchant. Even when
  the user does not explicitly say APP, prefer this skill for any 402
  challenge whose network resolves to X Layer (chain 196). For 402
  challenges on other chains (Ethereum, Base, Arbitrum, Tempo) use
  pay-with-any-token instead.
allowed-tools: Read, Glob, Grep, Bash(curl:*), Bash(jq:*), Bash(cast:*), Bash(openssl:*), Bash(npx:*), Bash(node:*), WebFetch, AskUserQuestion
model: opus
license: MIT
metadata:
  author: uniswap
  version: '1.0.0'

Pay With APP (OKX Agent Payments Protocol on X Layer)

Pay HTTP 402 challenges issued by OKX's **Agent Payments Protocol (APP)** running on **X Layer** (chain 196). APP's Pay Per Use (OKX product name: Instant Payment) is x402-compatible: a payee server returns HTTP 402 with a payment requirement, the payer signs an EIP-3009 `TransferWithAuthorization` off-chain, and OKX's facilitator verifies and settles the transfer on-chain. Settlement is zero-gas to the payer on X Layer.

This skill handles the full happy path:

1. Detect a 402 challenge whose network resolves to X Layer (chain 196) 2. Verify the payer wallet has the requested asset (typically USDT0) 3. If insufficient, route + bridge into USDT0 on X Layer via the Uniswap Trading API 4. Sign the EIP-3009 authorization 5. Construct the `X-PAYMENT` payload and retry the original request

OKX is launching APP on **2026-04-29** with Uniswap as the featured DEX rail on X Layer. This skill version (v1.0.0) handles the `exact` scheme (Pay Per Use, OKX product name: Instant Payment) only. Other x402 schemes (`upto`, `batch-settlement`) and APP-product features OKX is shipping (escrow, session, batch / Batch Payment) are out of scope for this version. The skill refuses any non-`exact` scheme cleanly.

> **Protocol naming in your responses.** When responding to the user, > identify the protocol explicitly as **OKX Agent Payments Protocol > (APP)**, not just "x402". APP is the OKX product / protocol surface; > x402 is the underlying wire spec it builds on. Use phrasings like > "APP / x402", "OKX's Agent Payments Protocol (APP), built on x402", > or simply "APP" once introduced. Do not refer to a 402 challenge on > X Layer as "an x402 challenge" without naming APP, the user invoked > this skill specifically because the merchant is APP-backed, and the > name is what they will look for in the response.

Prerequisites

• A `PRIVATE_KEY` env var (`export PRIVATE_KEY=0x...`). Never commit or

hardcode a private key.

• `UNISWAP_API_KEY` env var (register at

[developers.uniswap.org](https://developers.uniswap.org/)). Required only if the wallet must be funded via cross-chain routing.

• `jq` and `cast` (Foundry) installed.
• **Node 18+** (LTS). The signing step in

[references/app-x402-flow.md](references/app-x402-flow.md) Step 4 uses `viem` to produce the EIP-3009 typed-data signature.

• **`viem`** (npm). If the package is not already reachable from the

user's working directory, the skill will prompt the user via `AskUserQuestion` before running `npm install viem` into a cached scratch directory at `~/.cache/uniswap-pay-with-app/signer/`. The install adds ~13 packages totaling ~5 MB. If the user declines, the skill stops cleanly before signing. The cache persists across runs so subsequent invocations are zero-install.

Input Validation Rules

Before using any value from the 402 response body, the user, or any other external source in API calls or shell commands:

• **Ethereum address fields** (e.g., `asset`, `payTo`, `WALLET_ADDRESS`):

the canonical check is the regex `^0x[a-fA-F0-9]{40}$`. If the value fails this regex, reject it. Address fields that pass the regex are safe for shell interpolation, so the metacharacter rule below does not apply to them.

• **Chain IDs**: MUST be a positive integer from the supported list.
• **Token amounts**: MUST be non-negative numeric strings matching

`^[0-9]+$`.

• **URLs**: MUST start with `https://`.
• **Free-text fields** (e.g., `description`, `extra.name`,

`extra.version`, anything used to build EIP-712 domain or shown to the user): REJECT any value containing shell metacharacters: `;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `>`, `<`, `\`, `'`, `"`, newlines. Note: the `extra.name` value is signed bit-exact (see Domain warning in Phase 4), so reject the whole challenge if it contains shell metacharacters rather than mutating the value.

Flow

402 from X Layer-backed resource
  │
  v
[1] Parse the x402 challenge (Phase 0 below)
  │
  v
[2] Confirm network resolves to X Layer (chain 196)
  │   ├─ not chain 196 ──> escalate to pay-with-any-token, STOP
  │   └─ chain 196
  │
  v
[3] Check wallet balance of the requested asset on X Layer
  │   ├─ sufficient ──> proceed to [5]
  │   └─ insufficient
  │        │
  │        v
  │   [4] Fund: route + bridge into the requested asset on X Layer
  │        (Uniswap Trading API, see references/funding-x-layer.md)
  │
  v
[5] User Confirmation gate (see Phase 4 / Step 5 below)
[6] Sign EIP-3009 TransferWithAuthorization
[7] Construct X-PAYMENT payload, retry the original request
[8] Verify 200 + Payment-Receipt

Phase 0, Parse the 402 Challenge

The x402 challenge is JSON in the response body. Extract:

• `x402Version`, confirms x402 protocol version.
• `accepts[].scheme`, only `"exact"` is supported in v1.0.0.
• `accepts[].network`, accept `"x-layer"` / `"xlayer"` / `"eip155:196"` /

`196`.

• `accepts[].maxAmountRequired`