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:
- Detect a 402 challenge whose network resolves to X Layer (chain 196)
- Verify the payer wallet has the requested asset (typically USDT0)
- If insufficient, route + bridge into USDT0 on X Layer via the Uniswap
Trading API
- Sign the EIP-3009 authorization
- 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). 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 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, base units of the asset. Must match
^[0-9]+$ AND be strictly greater than zero. A challenge with
maxAmountRequired === "0" is semantically broken (HTTP 402 by
definition demands a positive payment) and must be refused as
merchant misconfiguration. Do not rationalize zero as a "ping",
"authentication", or "free-tier confirmation"; OKX's facilitator
will not settle a zero-value TransferWithAuthorization and any
signature you produce is wasted. Surface this to the user and stop.
accepts[].asset, token contract on X Layer.
accepts[].payTo, recipient address.
accepts[].resource, the URL the facilitator binds the payment to.
Extract this when present. Use it as the retry target. If the field is
absent, fall back to the original request URL.
accepts[].extra.name and accepts[].extra.version, EIP-712 domain
values for the asset.
accepts[].maxTimeoutSeconds, used for validBefore.
x402Version gate. Confirm x402Version === 1 immediately after
parsing. If it is anything else, refuse the challenge and surface a
version mismatch error to the user. v1.0.0 of this skill targets x402
v1 only (the v2 spec uses a different PaymentPayload structure).
Scheme gate. Confirm accepts[].scheme === "exact". The x402 spec
defines exact, upto, and batch-settlement schemes. v1.0.0 of this
skill supports exact only. If the chosen entry uses any other scheme,
refuse cleanly. (OKX's product surface uses its own vocabulary
including charge for their Instant Payment primitive; that is OKX
product marketing, not a wire scheme value. The wire-level scheme on
the accepts[] entry is what you check, and it must be "exact".)
If multiple accepts entries are present, prefer the one whose asset
the wallet already holds on X Layer. If multiple options are equally
viable, prefer USDT0 (deepest Uniswap funding-flow liquidity).
WOKB / native OKB likely not eligible as APP settlement assets. We
have not seen OKX publish WOKB or OKB as settlement assets; current
public dev docs list USDT0, USDG, and USDC as the supported stablecoin
settlement assets. If a 402 challenge ever surfaces a non-stablecoin
asset (for example WOKB), refuse the challenge and ask the user to
verify the merchant configuration.
Phase 1, Confirm Network is X Layer
case "$X402_NETWORK" in
x-layer|xlayer|"eip155:196"|196) X402_CHAIN_ID=196 ;;
*)
echo "Network is not X Layer. Use pay-with-any-token instead."
exit 1
;;
esac
If the network is not X Layer, stop and escalate to the
pay-with-any-token skill, which handles 402 challenges on Ethereum,
Base, Arbitrum, Tempo, and the other chains the Trading API supports.
Phase 2, Check Wallet Balance on X Layer
REQUIRED: You must have the user's source wallet address. Use
AskUserQuestion if not provided. Store as WALLET_ADDRESS.
ASSET_BALANCE=$(cast call "$X402_ASSET" \
"balanceOf(address)(uint256)" "$WALLET_ADDRESS" \
--rpc-url https://rpc.xlayer.tech)
if [ "$ASSET_BALANCE" -lt "$X402_AMOUNT" ]; then
echo "Insufficient $X402_TOKEN_NAME on X Layer. Funding required."
# Proceed to Phase 3 (funding)
fi
Phase 3, Fund USDT0 on X Layer (only if needed)
When the wallet lacks the requested asset, acquire it via the Uniswap
Trading API: EXACT_OUTPUT quote with tokenOutChainId=196 and
tokenOut set to the X Layer asset address. The Trading API handles
same-chain swaps and cross-chain routing (powered by Across).
Across coverage gap (verified 2026-04-27). Across Protocol does
not currently list X Layer (chain 196) as a supported destination. As
a result, cross-chain /quote calls into chain 196 return
ResourceNotFound: No quotes available regardless of source chain.
Same-chain X Layer swaps (Phase A in references/funding-x-layer.md)
are unaffected and work normally.
What this means for the agent in v1.0.0. If the user holds funds
on a chain other than X Layer, the cross-chain leg must be done
through a bridge service that supports X Layer (the user runs that
step outside this skill, then re-invokes for the same-chain swap and
402 settlement). Surface this honestly to the user, do not
recommend a specific bridge product (TODO: research and document a
co-marketing-aligned bridge recommendation in a follow-up).
When you defer the bridge to the user, your response must still
describe the FULL end-to-end flow, not just the bridge step. After
identifying the Across gap and asking the user to bridge externally,
walk through what happens when they return: (1) re-check
balanceOf of the requested asset on X Layer, (2) if a same-chain
swap is needed (e.g. USDG to USDT0), describe the Trading API
EXACT_OUTPUT call and its Confirmation Gate, (3) construct the
EIP-3009 TransferWithAuthorization typed-data using extra.name
and extra.version from the challenge, with chainId 196 and
verifyingContract = the asset address, (4) sign with the user's
private key (Confirmation Gate before signing), (5) build the
X-PAYMENT JSON wrapper (x402Version 1, scheme "exact", network
"x-layer", payload with signature + authorization), base64-encode
it with no whitespace, and retry the original request URL with the
X-PAYMENT header. Showing the full plan up front lets the user
see what they are committing to before they leave the skill, even
though signing happens after they return.
Default funding target = USDT0. If the 402 challenge requests a
different asset, fund into that asset directly only when it has reliable
Uniswap routing on X Layer:
| Asset |
Address |
Decimals |
Funding |
| USDT0 |
0x779Ded0c9e1022225f8E0630b35a9b54bE713736 |
6 |
✅ Direct via Trading API |
| USDG |
0x4ae46a509F6b1D9056937BA4500cb143933D2dc8 |
6 |
✅ Direct, or one-hop USDT0 to USDG |
| USDC |
0x74b7F16337b8972027F6196A17a631aC6dE26d22 |
6 |
⏳ No reliable Uniswap v3 routing on X Layer. The Trading API does not consistently return routes for USDC swaps on X Layer; available pool liquidity is too thin for reliable execution. If the merchant requires USDC, bridge USDC directly from a chain where it is liquid (Base, Arbitrum, Mainnet) using the Trading API rather than attempting a same-chain swap on X Layer. |
Detailed scripts and parameters: see
references/funding-x-layer.md.
Bridge buffer. Apply a 0.5% buffer to account for bridge fees.
Quotes expire in ~60 seconds, re-fetch if any delay before broadcast.
Minimum bridge recommendation. If the shortfall is < $5, top up to
$5 to amortize bridge gas on the source chain.
Gas and Routing Caveats
Surface these to the user before proceeding to fund, and call
AskUserQuestion (not an echoed bash prompt) before acting if any
apply:
- OKB on X Layer for same-chain swaps. OKX gas-sponsors only the
facilitator's settlement transfer. Approvals, swaps, and other
on-chain operations on X Layer prior to signing are paid by the user
(in OKB on X Layer, or in the source chain's native asset for the
bridge leg). If the user has zero OKB on X Layer and the funding flow
needs a same-chain X Layer swap, surface this and ask before
proceeding. Until OKX confirms a broader gas-sponsorship policy,
assume only the final settlement transfer is sponsored.
- Bridge destination token. If the wallet still lacks
$X402_ASSET after the funding flow's polling loop completes,
surface the source-chain tx hash and the Across explorer link to the
user. The bridge may have delivered a different variant on X Layer
(rare for current Across paths) or may have failed. v1.0.0 does not
auto-detect alternate-token arrival; the user must verify on-chain.
Phase 4, EIP-3009 Signing and X-PAYMENT Submission
OKX's APP Instant Payment uses x402's "exact" scheme: the payer signs a
TransferWithAuthorization typed-data message bound to the token's
own EIP-712 domain. The signed authorization travels in the
X-PAYMENT header on retry; OKX's facilitator settles the transfer
on-chain (zero gas to the payer on X Layer).
Step 5, User Confirmation
Every transaction this skill touches requires a separate
AskUserQuestion gate, with no exceptions for funding legs.
"Funding" is not a single transaction; it is several, and each one is
its own gate. The required gates, in order they typically fire:
- Source-chain ERC-20 approval to Permit2 / Universal Router (only
if
tokenIn is not native and the allowance is insufficient).
- Same-chain swap on the source chain (e.g. UNI to USDC on
Ethereum), if the funding plan includes a source-chain leg.
- Bridge submission to the cross-chain rail (Across, OKX bridge,
etc.). When the bridge step is user-initiated outside this skill,
the gate becomes "are you ready to leave the skill, run the bridge,
and re-invoke once funds land on X Layer?".
- Same-chain swap on X Layer (e.g. USDG to USDT0), if the funding
plan includes a destination-chain leg.
- EIP-3009
TransferWithAuthorization signature for the 402
settlement.
Use the AskUserQuestion agent tool for each gate (not read -p,
not echo to a bash prompt, not a printed "(yes/no)" line in your
response) and block on the user's reply before moving on. The
summary you present at every gate must cover:
- Action (approve, swap, bridge, sign EIP-3009 authorization).
- Amount and token (input AND output amounts for swaps and bridges).
- Source chain and destination chain (where they differ).
- Recipient (
payTo for the EIP-3009 step).
- Resource URL the payment is bound to.
- Estimated gas (where applicable).
Common failure mode. When describing a multi-step funding plan
in your response, do NOT collapse multiple transactions into a
single confirmation question like "Proceed with funding and
payment?". Each transaction needs its own gate at the moment it is
about to fire. A consolidated upfront "yes" is not consent for
later transactions; the user has not seen the live amounts, gas,
and recipient at the time those transactions execute.
Obtain explicit confirmation per gate. Each gate is independent.
Never auto-submit even if the user previously pre-authorized the
session, the call, or the wallet. A "yes" earlier in the flow does
not carry forward, and a "yes" to a multi-step plan is not a "yes" to
the individual transactions inside it.
What a correct gate looks like in your response. Whether you are
executing the skill in real time or describing a plan in text, every
transaction step MUST appear as its own labelled "Confirmation Gate"
block, with both the structured summary and an explicit
AskUserQuestion invocation. Reproduce this template literally for
each gate. Do not collapse the gate into a single line. Do not
describe the gate in passive voice ("we will confirm before
signing"). Show the gate as a discrete action.
Template (use for every gate, even when there is only one):
### Confirmation Gate N: <Action name>
| Field | Value |
| ------------ | ---------------------------------------- |
| Action | <approve / swap / bridge / sign EIP-3009>|
| Amount in | <amount + symbol on source chain> |
| Amount out | <amount + symbol on destination chain> |
| Source chain | <chain name + id> |
| Dest chain | <chain name + id> |
| Recipient | <address> |
| Resource URL | <url the payment is bound to> |
| Est. gas | <amount + token> |
Then call AskUserQuestion("Proceed with <action>?")
and BLOCK on the user's reply. If anything other than an explicit
"yes", stop and report.
A response that only lists fields without the
AskUserQuestion("Proceed?") + block step is not a gate, even if it
looks comprehensive. Name each gate as a discrete step and stop for
the user's reply before continuing.
What does NOT count as a confirmation gate. Emitting a bash script
that prints "⚠️ CONFIRMATION REQUIRED" and "(yes/no)" to stdout and
then continues with echo "Signing..." is not a gate, because the
script proceeds regardless of user input. A correct gate uses the
AskUserQuestion tool (or, if the user explicitly opts into shell-only
mode, an actual blocking read -p followed by an explicit yes/no
branch in the script). When in doubt, prefer AskUserQuestion.
Shared-wallet race. If the wallet is shared (for example, multiple
agents running concurrently against the same key), the balance can be
drained between balance check and submit. Re-check balanceOf at the
moment of confirmation as well.
Step 6, Sign and Submit
Detailed steps including domain construction, nonce generation, signing
with viem, payload assembly, and retry: see
references/app-x402-flow.md. On retry,
target the URL from accepts[].resource if it was present in the
challenge, otherwise the original request URL.
Domain warning. verifyingContract is the token contract, not
a separate verifier. Use name and version from the challenge's
extra field, do not assume defaults. Different tokens have different
domain values. An incorrect domain produces a signature the
facilitator will reject with another 402.
Bit-exact UTF-8 for extra.name. The EIP-712 domain hash is
byte-exact. The name field in extra must be passed through
unchanged from the challenge bytes. Do not normalize it, do not
lowercase it, do not substitute ASCII T (U+0054) for Unicode ₮
(U+20AE), do not collapse Unicode forms (NFC vs NFD). For example, a
challenge that returns "USD₮0" must be signed as "USD₮0"; reading
it as "USDT0" will produce a signature the facilitator rejects with
another 402. Pass the raw bytes of extra.name straight into the
EIP-712 domain.
Error Handling
| Situation |
Action |
402 challenge has no network field |
Inspect challenge body; if chainId resolves to 196 use this skill, otherwise escalate to pay-with-any-token |
| Network is not chain 196 |
Escalate to pay-with-any-token |
x402Version !== 1 |
Refuse cleanly; surface a version mismatch error. v1.0.0 of this skill targets x402 v1 only. |
accepts[].scheme !== "exact" |
Refuse cleanly; v1.0.0 supports the exact scheme only. Other x402 schemes (upto, batch-settlement) are out of scope. |
accepts[].maxAmountRequired === "0" |
Refuse cleanly as merchant misconfiguration. HTTP 402 demands a positive payment; OKX's facilitator will not settle a zero-value transfer. Do not sign and do not rationalize zero as a ping, auth check, or free tier. |
| APP requests USDC on X Layer |
Surface a clear caveat: USDC has no reliable Uniswap v3 routing on X Layer. Suggest bridging USDC directly from a chain where it is liquid (Base, Arbitrum, Mainnet), or asking about USDT0. |
| Insufficient asset on X Layer |
Trigger funding flow (Phase 3) |
| Trading API returns 400 |
Log request/response; check amount formatting and address checksums |
| Trading API returns 429 |
Back off and retry with exponential delay |
| Quote expired |
Re-fetch quote; do not reuse old permitData |
| Bridge times out |
Check Across bridge explorer; do not re-submit |
| EIP-3009 signature rejected (402 on retry) |
Verify domain name / version from extra (byte-exact, including any non-ASCII characters), check validBefore is fresh, confirm nonce was unused |
| Amount mismatch on retry |
Recompute base units using on-chain decimals() of the actual asset; do not assume 6 |
On-chain settlement reverts (transferFrom failed) |
Re-check balanceOf at retry time; the balance may have been drained between sign and submit (shared wallet, concurrent agent, manual transfer). Surface to the user before retrying. |
User asks about escrow / session / batch / upto |
Inform that this skill version covers Instant Payment (exact scheme) only. Other primitives are out of scope for v1.0.0; a v1.x follow-up will track them as OKX ships. |
Key Addresses and References
X Layer (chain 196)
- Chain ID:
196
- Public RPC:
https://rpc.xlayer.tech
- USDT0:
0x779Ded0c9e1022225f8E0630b35a9b54bE713736 (decimals 6)
- USDG:
0x4ae46a509F6b1D9056937BA4500cb143933D2dc8 (decimals 6)
- USDC:
0x74b7F16337b8972027F6196A17a631aC6dE26d22 (decimals 6, no
reliable Uniswap routing on X Layer; bridge from a liquid chain)
- WOKB (wrapped native):
0xe538905cf8410324e03A5A23C1c177a474D59b2b
(decimals 18)
- Uniswap V3 Factory:
0x4B2ab38DBF28D31D467aA8993f6c2585981D6804
- SwapRouter02:
0x4f0C28f5926AFDA16bf2506D5D9e57Ea190f9bcA
- Universal Router 2.1:
0xDa00aE15d3A71466517129255255db7c0c0956d3
- QuoterV2:
0xD1b797D92d87B688193A2B976eFc8D577D204343
- Permit2:
0x000000000022D473030F116dDEE9F6B43aC78BA3
- USDT0/USDG pool:
0x0cBe0dBE1400e57f371a38BD3b9bC80F7C3676dA
- USDT0/WOKB pool:
0x63d62734847E55A266FCa4219A9aD0a02D5F6e02
Uniswap Trading API
- Base URL:
https://trade-api.gateway.uniswap.org/v1
- Header:
x-api-key: $UNISWAP_API_KEY
- Header:
x-universal-router-version: 2.1.1
- Supported chains include 1, 8453, 42161, 10, 137, 130, 196, and more
(see Trading API supported-chains docs).
The on-chain Universal Router contract on X Layer is labeled 2.1
(deployed at 0xDa00aE15d3A71466517129255255db7c0c0956d3 above). The
Trading API expects the header value 2.1.1, which is the API's
internal version-string for the routing path that targets the same
Universal Router 2.1 contract. The two version strings refer to
related but distinct things; do not substitute one for the other.
OKX APP
- APP overview / dev docs:
https://web3.okx.com/onchainos/dev-docs/payments/x402-introduction
- OKX onchainos-skills repo:
https://github.com/okx/onchainos-skills
- x402 spec:
https://github.com/coinbase/x402
Related Skills
- pay-with-any-token, sibling skill
for HTTP 402 challenges on chains other than X Layer (Ethereum, Base,
Arbitrum, Tempo, etc.). Use that skill for non-X-Layer challenges.
- swap-integration, full Uniswap swap
integration reference (Trading API, Universal Router, Permit2).
1---
2name: pay-with-app
3description: >
4 Pay HTTP 402 payment challenges issued by OKX's Agent Payments Protocol
5 (APP) on X Layer using tokens from any chain via the Uniswap Trading API.
6 Use this skill whenever the user encounters a 402 challenge whose network
7 resolves to X Layer (chain 196), mentions "APP", "Agent Payments
8 Protocol", "OKX agent payment", "OKX Onchain OS", "OKX agentic wallet",
9 "x402 on X Layer", "USDT0", "x42", "Instant Payment", "Batch Payment",
10 "pay for X Layer API", or wants to pay an OKX-backed merchant. Even when
11 the user does not explicitly say APP, prefer this skill for any 402
12 challenge whose network resolves to X Layer (chain 196). For 402
13 challenges on other chains (Ethereum, Base, Arbitrum, Tempo) use
14 pay-with-any-token instead.
15allowed-tools: Read, Glob, Grep, Bash(curl:*), Bash(jq:*), Bash(cast:*), Bash(openssl:*), Bash(npx:*), Bash(node:*), WebFetch, AskUserQuestion
16model: opus
17license: MIT
18metadata:
19 source: https://skillmd.com/skills/uniswap/pay-with-app
20 author: uniswap
21 version: '1.0.0'
22---
23
24# Pay With APP (OKX Agent Payments Protocol on X Layer)
25
26Pay HTTP 402 challenges issued by OKX's **Agent Payments Protocol (APP)**
27running on **X Layer** (chain 196). APP's Pay Per Use (OKX product name:
28Instant Payment) is x402-compatible: a payee server returns HTTP 402 with
29a payment requirement, the payer signs an EIP-3009
30`TransferWithAuthorization` off-chain, and OKX's facilitator verifies and
31settles the transfer on-chain. Settlement is zero-gas to the payer on X
32Layer.
33
34This skill handles the full happy path:
35
361. Detect a 402 challenge whose network resolves to X Layer (chain 196)
372. Verify the payer wallet has the requested asset (typically USDT0)
383. If insufficient, route + bridge into USDT0 on X Layer via the Uniswap
39 Trading API
404. Sign the EIP-3009 authorization
415. Construct the `X-PAYMENT` payload and retry the original request
42
43OKX is launching APP on **2026-04-29** with Uniswap as the featured DEX
44rail on X Layer. This skill version (v1.0.0) handles the `exact` scheme
45(Pay Per Use, OKX product name: Instant Payment) only. Other x402 schemes
46(`upto`, `batch-settlement`) and APP-product features OKX is shipping
47(escrow, session, batch / Batch Payment) are out of scope for this
48version. The skill refuses any non-`exact` scheme cleanly.
49
50> **Protocol naming in your responses.** When responding to the user,
51> identify the protocol explicitly as **OKX Agent Payments Protocol
52> (APP)**, not just "x402". APP is the OKX product / protocol surface;
53> x402 is the underlying wire spec it builds on. Use phrasings like
54> "APP / x402", "OKX's Agent Payments Protocol (APP), built on x402",
55> or simply "APP" once introduced. Do not refer to a 402 challenge on
56> X Layer as "an x402 challenge" without naming APP, the user invoked
57> this skill specifically because the merchant is APP-backed, and the
58> name is what they will look for in the response.
59
60## Prerequisites
61
62- A `PRIVATE_KEY` env var (`export PRIVATE_KEY=0x...`). Never commit or
63 hardcode a private key.
64- `UNISWAP_API_KEY` env var (register at
65 [developers.uniswap.org](https://developers.uniswap.org/)). Required
66 only if the wallet must be funded via cross-chain routing.
67- `jq` and `cast` (Foundry) installed.
68- **Node 18+** (LTS). The signing step in
69 [references/app-x402-flow.md](references/app-x402-flow.md) Step 4 uses
70 `viem` to produce the EIP-3009 typed-data signature.
71- **`viem`** (npm). If the package is not already reachable from the
72 user's working directory, the skill will prompt the user via
73 `AskUserQuestion` before running `npm install viem` into a cached
74 scratch directory at `~/.cache/uniswap-pay-with-app/signer/`. The
75 install adds ~13 packages totaling ~5 MB. If the user declines, the
76 skill stops cleanly before signing. The cache persists across runs so
77 subsequent invocations are zero-install.
78
79## Input Validation Rules
80
81Before using any value from the 402 response body, the user, or any other
82external source in API calls or shell commands:
83
84- **Ethereum address fields** (e.g., `asset`, `payTo`, `WALLET_ADDRESS`):
85 the canonical check is the regex `^0x[a-fA-F0-9]{40}$`. If the value
86 fails this regex, reject it. Address fields that pass the regex are
87 safe for shell interpolation, so the metacharacter rule below does not
88 apply to them.
89- **Chain IDs**: MUST be a positive integer from the supported list.
90- **Token amounts**: MUST be non-negative numeric strings matching
91 `^[0-9]+$`.
92- **URLs**: MUST start with `https://`.
93- **Free-text fields** (e.g., `description`, `extra.name`,
94 `extra.version`, anything used to build EIP-712 domain or shown to the
95 user): REJECT any value containing shell metacharacters: `;`, `|`, `&`,
96 `$`, `` ` ``, `(`, `)`, `>`, `<`, `\`, `'`, `"`, newlines. Note: the
97 `extra.name` value is signed bit-exact (see Domain warning in Phase 4),
98 so reject the whole challenge if it contains shell metacharacters
99 rather than mutating the value.
100
101## Flow
102
103```text
104402 from X Layer-backed resource
105 │
106 v
107[1] Parse the x402 challenge (Phase 0 below)
108 │
109 v
110[2] Confirm network resolves to X Layer (chain 196)
111 │ ├─ not chain 196 ──> escalate to pay-with-any-token, STOP
112 │ └─ chain 196
113 │
114 v
115[3] Check wallet balance of the requested asset on X Layer
116 │ ├─ sufficient ──> proceed to [5]
117 │ └─ insufficient
118 │ │
119 │ v
120 │ [4] Fund: route + bridge into the requested asset on X Layer
121 │ (Uniswap Trading API, see references/funding-x-layer.md)
122 │
123 v
124[5] User Confirmation gate (see Phase 4 / Step 5 below)
125[6] Sign EIP-3009 TransferWithAuthorization
126[7] Construct X-PAYMENT payload, retry the original request
127[8] Verify 200 + Payment-Receipt
128```
129
130## Phase 0, Parse the 402 Challenge
131
132The x402 challenge is JSON in the response body. Extract:
133
134- `x402Version`, confirms x402 protocol version.
135- `accepts[].scheme`, only `"exact"` is supported in v1.0.0.
136- `accepts[].network`, accept `"x-layer"` / `"xlayer"` / `"eip155:196"` /
137 `196`.
138- `accepts[].maxAmountRequired`, base units of the asset. Must match
139 `^[0-9]+$` AND be **strictly greater than zero**. A challenge with
140 `maxAmountRequired === "0"` is semantically broken (HTTP 402 by
141 definition demands a positive payment) and must be refused as
142 merchant misconfiguration. Do not rationalize zero as a "ping",
143 "authentication", or "free-tier confirmation"; OKX's facilitator
144 will not settle a zero-value `TransferWithAuthorization` and any
145 signature you produce is wasted. Surface this to the user and stop.
146- `accepts[].asset`, token contract on X Layer.
147- `accepts[].payTo`, recipient address.
148- `accepts[].resource`, the URL the facilitator binds the payment to.
149 Extract this when present. Use it as the retry target. If the field is
150 absent, fall back to the original request URL.
151- `accepts[].extra.name` and `accepts[].extra.version`, EIP-712 domain
152 values for the asset.
153- `accepts[].maxTimeoutSeconds`, used for `validBefore`.
154
155> **x402Version gate.** Confirm `x402Version === 1` immediately after
156> parsing. If it is anything else, refuse the challenge and surface a
157> version mismatch error to the user. v1.0.0 of this skill targets x402
158> v1 only (the v2 spec uses a different PaymentPayload structure).
159>
160> **Scheme gate.** Confirm `accepts[].scheme === "exact"`. The x402 spec
161> defines `exact`, `upto`, and `batch-settlement` schemes. v1.0.0 of this
162> skill supports `exact` only. If the chosen entry uses any other scheme,
163> refuse cleanly. (OKX's product surface uses its own vocabulary
164> including `charge` for their Instant Payment primitive; that is OKX
165> product marketing, not a wire scheme value. The wire-level scheme on
166> the `accepts[]` entry is what you check, and it must be `"exact"`.)
167
168If multiple `accepts` entries are present, prefer the one whose `asset`
169the wallet already holds on X Layer. If multiple options are equally
170viable, prefer USDT0 (deepest Uniswap funding-flow liquidity).
171
172**WOKB / native OKB likely not eligible as APP settlement assets.** We
173have not seen OKX publish WOKB or OKB as settlement assets; current
174public dev docs list USDT0, USDG, and USDC as the supported stablecoin
175settlement assets. If a 402 challenge ever surfaces a non-stablecoin
176`asset` (for example `WOKB`), refuse the challenge and ask the user to
177verify the merchant configuration.
178
179## Phase 1, Confirm Network is X Layer
180
181```bash
182case "$X402_NETWORK" in
183 x-layer|xlayer|"eip155:196"|196) X402_CHAIN_ID=196 ;;
184 *)
185 echo "Network is not X Layer. Use pay-with-any-token instead."
186 exit 1
187 ;;
188esac
189```
190
191> If the network is not X Layer, **stop** and escalate to the
192> `pay-with-any-token` skill, which handles 402 challenges on Ethereum,
193> Base, Arbitrum, Tempo, and the other chains the Trading API supports.
194
195## Phase 2, Check Wallet Balance on X Layer
196
197> **REQUIRED:** You must have the user's source wallet address. Use
198> `AskUserQuestion` if not provided. Store as `WALLET_ADDRESS`.
199
200```bash
201ASSET_BALANCE=$(cast call "$X402_ASSET" \
202 "balanceOf(address)(uint256)" "$WALLET_ADDRESS" \
203 --rpc-url https://rpc.xlayer.tech)
204
205if [ "$ASSET_BALANCE" -lt "$X402_AMOUNT" ]; then
206 echo "Insufficient $X402_TOKEN_NAME on X Layer. Funding required."
207 # Proceed to Phase 3 (funding)
208fi
209```
210
211## Phase 3, Fund USDT0 on X Layer (only if needed)
212
213When the wallet lacks the requested asset, acquire it via the Uniswap
214Trading API: `EXACT_OUTPUT` quote with `tokenOutChainId=196` and
215`tokenOut` set to the X Layer asset address. The Trading API handles
216same-chain swaps and cross-chain routing (powered by Across).
217
218> **Across coverage gap (verified 2026-04-27).** Across Protocol does
219> not currently list X Layer (chain 196) as a supported destination. As
220> a result, cross-chain `/quote` calls into chain 196 return
221> `ResourceNotFound: No quotes available` regardless of source chain.
222> Same-chain X Layer swaps (Phase A in `references/funding-x-layer.md`)
223> are unaffected and work normally.
224>
225> **What this means for the agent in v1.0.0.** If the user holds funds
226> on a chain other than X Layer, the cross-chain leg must be done
227> through a bridge service that supports X Layer (the user runs that
228> step outside this skill, then re-invokes for the same-chain swap and
229> 402 settlement). Surface this honestly to the user, do not
230> recommend a specific bridge product (TODO: research and document a
231> co-marketing-aligned bridge recommendation in a follow-up).
232>
233> **When you defer the bridge to the user, your response must still
234> describe the FULL end-to-end flow**, not just the bridge step. After
235> identifying the Across gap and asking the user to bridge externally,
236> walk through what happens when they return: (1) re-check
237> `balanceOf` of the requested asset on X Layer, (2) if a same-chain
238> swap is needed (e.g. USDG to USDT0), describe the Trading API
239> EXACT_OUTPUT call and its Confirmation Gate, (3) construct the
240> EIP-3009 `TransferWithAuthorization` typed-data using `extra.name`
241> and `extra.version` from the challenge, with chainId 196 and
242> `verifyingContract` = the asset address, (4) sign with the user's
243> private key (Confirmation Gate before signing), (5) build the
244> `X-PAYMENT` JSON wrapper (x402Version 1, scheme "exact", network
245> "x-layer", payload with signature + authorization), base64-encode
246> it with no whitespace, and retry the original request URL with the
247> `X-PAYMENT` header. Showing the full plan up front lets the user
248> see what they are committing to before they leave the skill, even
249> though signing happens after they return.
250
251**Default funding target = USDT0.** If the 402 challenge requests a
252different asset, fund into that asset directly only when it has reliable
253Uniswap routing on X Layer:
254
255| Asset | Address | Decimals | Funding |
256| ----- | -------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
257| USDT0 | `0x779Ded0c9e1022225f8E0630b35a9b54bE713736` | 6 | ✅ Direct via Trading API |
258| USDG | `0x4ae46a509F6b1D9056937BA4500cb143933D2dc8` | 6 | ✅ Direct, or one-hop USDT0 to USDG |
259| USDC | `0x74b7F16337b8972027F6196A17a631aC6dE26d22` | 6 | ⏳ No reliable Uniswap v3 routing on X Layer. The Trading API does not consistently return routes for USDC swaps on X Layer; available pool liquidity is too thin for reliable execution. If the merchant requires USDC, bridge USDC directly from a chain where it is liquid (Base, Arbitrum, Mainnet) using the Trading API rather than attempting a same-chain swap on X Layer. |
260
261Detailed scripts and parameters: see
262[references/funding-x-layer.md](references/funding-x-layer.md).
263
264> **Bridge buffer.** Apply a 0.5% buffer to account for bridge fees.
265> Quotes expire in ~60 seconds, re-fetch if any delay before broadcast.
266>
267> **Minimum bridge recommendation.** If the shortfall is < $5, top up to
268> $5 to amortize bridge gas on the source chain.
269
270### Gas and Routing Caveats
271
272Surface these to the user before proceeding to fund, and **call
273`AskUserQuestion`** (not an echoed bash prompt) before acting if any
274apply:
275
276- **OKB on X Layer for same-chain swaps.** OKX gas-sponsors only the
277 facilitator's settlement transfer. Approvals, swaps, and other
278 on-chain operations on X Layer prior to signing are paid by the user
279 (in OKB on X Layer, or in the source chain's native asset for the
280 bridge leg). If the user has zero OKB on X Layer and the funding flow
281 needs a same-chain X Layer swap, surface this and ask before
282 proceeding. Until OKX confirms a broader gas-sponsorship policy,
283 assume only the final settlement transfer is sponsored.
284- **Bridge destination token.** If the wallet still lacks
285 `$X402_ASSET` after the funding flow's polling loop completes,
286 surface the source-chain tx hash and the Across explorer link to the
287 user. The bridge may have delivered a different variant on X Layer
288 (rare for current Across paths) or may have failed. v1.0.0 does not
289 auto-detect alternate-token arrival; the user must verify on-chain.
290
291## Phase 4, EIP-3009 Signing and X-PAYMENT Submission
292
293OKX's APP Instant Payment uses x402's `"exact"` scheme: the payer signs a
294`TransferWithAuthorization` typed-data message bound to the **token's
295own** EIP-712 domain. The signed authorization travels in the
296`X-PAYMENT` header on retry; OKX's facilitator settles the transfer
297on-chain (zero gas to the payer on X Layer).
298
299### Step 5, User Confirmation
300
301**Every** transaction this skill touches requires a separate
302`AskUserQuestion` gate, with no exceptions for funding legs.
303"Funding" is not a single transaction; it is several, and each one is
304its own gate. The required gates, in order they typically fire:
305
3061. **Source-chain ERC-20 approval** to Permit2 / Universal Router (only
307 if `tokenIn` is not native and the allowance is insufficient).
3082. **Same-chain swap** on the source chain (e.g. UNI to USDC on
309 Ethereum), if the funding plan includes a source-chain leg.
3103. **Bridge submission** to the cross-chain rail (Across, OKX bridge,
311 etc.). When the bridge step is user-initiated outside this skill,
312 the gate becomes "are you ready to leave the skill, run the bridge,
313 and re-invoke once funds land on X Layer?".
3144. **Same-chain swap on X Layer** (e.g. USDG to USDT0), if the funding
315 plan includes a destination-chain leg.
3165. **EIP-3009 `TransferWithAuthorization` signature** for the 402
317 settlement.
318
319Use the **`AskUserQuestion` agent tool** for each gate (not `read -p`,
320not `echo` to a bash prompt, not a printed "(yes/no)" line in your
321response) and **block on the user's reply** before moving on. The
322summary you present at every gate must cover:
323
324- Action (approve, swap, bridge, sign EIP-3009 authorization).
325- Amount and token (input AND output amounts for swaps and bridges).
326- Source chain and destination chain (where they differ).
327- Recipient (`payTo` for the EIP-3009 step).
328- Resource URL the payment is bound to.
329- Estimated gas (where applicable).
330
331> **Common failure mode.** When describing a multi-step funding plan
332> in your response, do NOT collapse multiple transactions into a
333> single confirmation question like "Proceed with funding and
334> payment?". Each transaction needs its own gate at the moment it is
335> about to fire. A consolidated upfront "yes" is not consent for
336> later transactions; the user has not seen the live amounts, gas,
337> and recipient at the time those transactions execute.
338
339Obtain explicit confirmation per gate. Each gate is independent.
340**Never** auto-submit even if the user previously pre-authorized the
341session, the call, or the wallet. A "yes" earlier in the flow does
342not carry forward, and a "yes" to a multi-step plan is not a "yes" to
343the individual transactions inside it.
344
345> **What a correct gate looks like in your response.** Whether you are
346> executing the skill in real time or describing a plan in text, every
347> transaction step MUST appear as its own labelled "Confirmation Gate"
348> block, with both the structured summary and an explicit
349> `AskUserQuestion` invocation. Reproduce this template literally for
350> each gate. Do not collapse the gate into a single line. Do not
351> describe the gate in passive voice ("we will confirm before
352> signing"). Show the gate as a discrete action.
353>
354> **Template (use for every gate, even when there is only one):**
355>
356> ```text
357> ### Confirmation Gate N: <Action name>
358>
359> | Field | Value |
360> | ------------ | ---------------------------------------- |
361> | Action | <approve / swap / bridge / sign EIP-3009>|
362> | Amount in | <amount + symbol on source chain> |
363> | Amount out | <amount + symbol on destination chain> |
364> | Source chain | <chain name + id> |
365> | Dest chain | <chain name + id> |
366> | Recipient | <address> |
367> | Resource URL | <url the payment is bound to> |
368> | Est. gas | <amount + token> |
369>
370> Then call AskUserQuestion("Proceed with <action>?")
371> and BLOCK on the user's reply. If anything other than an explicit
372> "yes", stop and report.
373> ```
374>
375> A response that only lists fields without the
376> `AskUserQuestion("Proceed?") + block` step is not a gate, even if it
377> looks comprehensive. Name each gate as a discrete step and stop for
378> the user's reply before continuing.
379
380<!-- markdownlint-disable-next-line -->
381
382> **What does NOT count as a confirmation gate.** Emitting a bash script
383> that prints `"⚠️ CONFIRMATION REQUIRED"` and `"(yes/no)"` to stdout and
384> then continues with `echo "Signing..."` is **not** a gate, because the
385> script proceeds regardless of user input. A correct gate uses the
386> `AskUserQuestion` tool (or, if the user explicitly opts into shell-only
387> mode, an actual blocking `read -p` followed by an explicit `yes`/`no`
388> branch in the script). When in doubt, prefer `AskUserQuestion`.
389
390<!-- markdownlint-disable-next-line -->
391
392> **Shared-wallet race.** If the wallet is shared (for example, multiple
393> agents running concurrently against the same key), the balance can be
394> drained between balance check and submit. Re-check `balanceOf` at the
395> moment of confirmation as well.
396
397### Step 6, Sign and Submit
398
399Detailed steps including domain construction, nonce generation, signing
400with viem, payload assembly, and retry: see
401[references/app-x402-flow.md](references/app-x402-flow.md). On retry,
402target the URL from `accepts[].resource` if it was present in the
403challenge, otherwise the original request URL.
404
405> **Domain warning.** `verifyingContract` is the **token contract**, not
406> a separate verifier. Use `name` and `version` from the challenge's
407> `extra` field, do not assume defaults. Different tokens have different
408> domain values. An incorrect domain produces a signature the
409> facilitator will reject with another 402.
410>
411> **Bit-exact UTF-8 for `extra.name`.** The EIP-712 domain hash is
412> byte-exact. The `name` field in `extra` must be passed through
413> unchanged from the challenge bytes. Do not normalize it, do not
414> lowercase it, do not substitute ASCII `T` (U+0054) for Unicode `₮`
415> (U+20AE), do not collapse Unicode forms (NFC vs NFD). For example, a
416> challenge that returns `"USD₮0"` must be signed as `"USD₮0"`; reading
417> it as `"USDT0"` will produce a signature the facilitator rejects with
418> another 402. Pass the raw bytes of `extra.name` straight into the
419> EIP-712 domain.
420
421## Error Handling
422
423| Situation | Action |
424| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
425| 402 challenge has no `network` field | Inspect challenge body; if `chainId` resolves to 196 use this skill, otherwise escalate to `pay-with-any-token` |
426| Network is not chain 196 | Escalate to `pay-with-any-token` |
427| `x402Version !== 1` | Refuse cleanly; surface a version mismatch error. v1.0.0 of this skill targets x402 v1 only. |
428| `accepts[].scheme !== "exact"` | Refuse cleanly; v1.0.0 supports the `exact` scheme only. Other x402 schemes (`upto`, `batch-settlement`) are out of scope. |
429| `accepts[].maxAmountRequired === "0"` | Refuse cleanly as merchant misconfiguration. HTTP 402 demands a positive payment; OKX's facilitator will not settle a zero-value transfer. Do not sign and do not rationalize zero as a ping, auth check, or free tier. |
430| APP requests USDC on X Layer | Surface a clear caveat: USDC has no reliable Uniswap v3 routing on X Layer. Suggest bridging USDC directly from a chain where it is liquid (Base, Arbitrum, Mainnet), or asking about USDT0. |
431| Insufficient asset on X Layer | Trigger funding flow (Phase 3) |
432| Trading API returns 400 | Log request/response; check amount formatting and address checksums |
433| Trading API returns 429 | Back off and retry with exponential delay |
434| Quote expired | Re-fetch quote; do not reuse old `permitData` |
435| Bridge times out | Check Across bridge explorer; do not re-submit |
436| EIP-3009 signature rejected (402 on retry) | Verify domain `name` / `version` from `extra` (byte-exact, including any non-ASCII characters), check `validBefore` is fresh, confirm `nonce` was unused |
437| Amount mismatch on retry | Recompute base units using on-chain `decimals()` of the actual asset; do not assume 6 |
438| On-chain settlement reverts (`transferFrom` failed) | Re-check `balanceOf` at retry time; the balance may have been drained between sign and submit (shared wallet, concurrent agent, manual transfer). Surface to the user before retrying. |
439| User asks about escrow / session / batch / `upto` | Inform that this skill version covers Instant Payment (`exact` scheme) only. Other primitives are out of scope for v1.0.0; a v1.x follow-up will track them as OKX ships. |
440
441## Key Addresses and References
442
443### X Layer (chain 196)
444
445- **Chain ID**: `196`
446- **Public RPC**: `https://rpc.xlayer.tech`
447- **USDT0**: `0x779Ded0c9e1022225f8E0630b35a9b54bE713736` (decimals 6)
448- **USDG**: `0x4ae46a509F6b1D9056937BA4500cb143933D2dc8` (decimals 6)
449- **USDC**: `0x74b7F16337b8972027F6196A17a631aC6dE26d22` (decimals 6, no
450 reliable Uniswap routing on X Layer; bridge from a liquid chain)
451- **WOKB** (wrapped native): `0xe538905cf8410324e03A5A23C1c177a474D59b2b`
452 (decimals 18)
453- **Uniswap V3 Factory**: `0x4B2ab38DBF28D31D467aA8993f6c2585981D6804`
454- **SwapRouter02**: `0x4f0C28f5926AFDA16bf2506D5D9e57Ea190f9bcA`
455- **Universal Router 2.1**:
456 `0xDa00aE15d3A71466517129255255db7c0c0956d3`
457- **QuoterV2**: `0xD1b797D92d87B688193A2B976eFc8D577D204343`
458- **Permit2**: `0x000000000022D473030F116dDEE9F6B43aC78BA3`
459- **USDT0/USDG pool**: `0x0cBe0dBE1400e57f371a38BD3b9bC80F7C3676dA`
460- **USDT0/WOKB pool**: `0x63d62734847E55A266FCa4219A9aD0a02D5F6e02`
461
462### Uniswap Trading API
463
464- Base URL: `https://trade-api.gateway.uniswap.org/v1`
465- Header: `x-api-key: $UNISWAP_API_KEY`
466- Header: `x-universal-router-version: 2.1.1`
467- Supported chains include 1, 8453, 42161, 10, 137, 130, **196**, and more
468 (see Trading API supported-chains docs).
469
470> The on-chain Universal Router contract on X Layer is labeled **2.1**
471> (deployed at `0xDa00aE15d3A71466517129255255db7c0c0956d3` above). The
472> Trading API expects the header value `2.1.1`, which is the API's
473> internal version-string for the routing path that targets the same
474> Universal Router 2.1 contract. The two version strings refer to
475> related but distinct things; do not substitute one for the other.
476
477### OKX APP
478
479- **APP overview / dev docs**:
480 `https://web3.okx.com/onchainos/dev-docs/payments/x402-introduction`
481- **OKX onchainos-skills repo**: `https://github.com/okx/onchainos-skills`
482- **x402 spec**: `https://github.com/coinbase/x402`
483
484## Related Skills
485
486- [pay-with-any-token](../pay-with-any-token/SKILL.md), sibling skill
487 for HTTP 402 challenges on chains other than X Layer (Ethereum, Base,
488 Arbitrum, Tempo, etc.). Use that skill for non-X-Layer challenges.
489- [swap-integration](../swap-integration/SKILL.md), full Uniswap swap
490 integration reference (Trading API, Universal Router, Permit2).