/pay-with-any-token

name: pay-with-any-token
description: >
  Pay HTTP 402 payment challenges using tokens via the Tempo CLI and Uniswap
  Trading API. Use when the user encounters a 402 Payment Required response,
  needs to fulfill a machine payment, mentions "MPP", "Tempo payment", "pay for
  API access", "HTTP 402", "x402", "machine payment protocol",
  "pay-with-any-token", "use tempo", "tempo request", or "tempo wallet".
allowed-tools: Read, Glob, Grep, Bash(curl:*), Bash(jq:*), Bash(cast:*), Bash(tempo:*), Bash(*/.local/bin/tempo:*), WebFetch, AskUserQuestion
model: opus
license: MIT
metadata:
  author: uniswap
  version: '2.0.0'

Pay With Tokens

Use the **Tempo CLI** to call paid APIs and handle 402 challenges automatically. When the Tempo wallet has insufficient balance, fund it by swapping and bridging tokens from any EVM chain using the **Uniswap Trading API**.

Tempo CLI Setup

Run these commands in order. Do not skip steps.

**Step 1 — Install:**

mkdir -p "$HOME/.local/bin" \
  && curl -fsSL https://tempo.xyz/install -o /tmp/tempo_install.sh \
  && TEMPO_BIN_DIR="$HOME/.local/bin" bash /tmp/tempo_install.sh

**Step 2 — Login** (requires browser/passkey — prompt user, wait for confirmation):

"$HOME/.local/bin/tempo" wallet login

> When run by agents, use a long command timeout (at least 16 minutes).

**Step 3 — Confirm readiness:**

"$HOME/.local/bin/tempo" wallet -t whoami

> **Rules:** Do not use `sudo`. Use full absolute paths (`$HOME/.local/bin/tempo`) > — do not rely on `export PATH`. If `$HOME` does not expand, use the literal > absolute path.

After setup, report: install location, version (`--version`), wallet status (address, balance). If balance is 0, direct user to `tempo wallet fund`.

> **Minimum balance reserve:** Keep at least **0.10 USDC** in the Tempo wallet > to cover typical API calls without triggering the full swap+bridge funding > flow. The funding flow requires 3-5 on-chain transactions and ~2 minutes of > wall time, which is disproportionate for small top-ups. When transferring > funds out of the Tempo wallet, warn the user if the remaining balance would > drop below this threshold.

Using Tempo Services

# Discover services
"$HOME/.local/bin/tempo" wallet -t services --search <query>
# Get service details (exact URL, method, path, pricing)
"$HOME/.local/bin/tempo" wallet -t services <SERVICE_ID>
# Make a paid request
"$HOME/.local/bin/tempo" request -t -X POST \
  --json '{"input":"..."}' <SERVICE_URL>/<ENDPOINT_PATH>

• Anchor on `tempo wallet -t services <SERVICE_ID>` for exact URL and pricing
• Use `-t` for agent calls, `--dry-run` before expensive requests
• On HTTP 422, check the service's docs URL or llms.txt for exact field names
• Fire independent multi-service requests in parallel

> **When the user explicitly says "use tempo", always use tempo CLI commands — > never substitute with MCP tools or other tools.**

---

MPP 402 Payment Loop

Every `tempo request` call follows this loop. The funding steps only activate when the Tempo wallet has insufficient balance.

tempo request -> 200 ─────────────────────────────> return result
             -> 402 MPP challenge
                  │
                  v
         [1] Check Tempo wallet balance
             tempo wallet -t whoami -> available balance
                  │
                  ├─ sufficient ──────────────────> tempo handles payment
                  │                                  automatically -> 200
                  │
                  └─ insufficient
                       │
                       v
              [2] Fund Tempo wallet
                  (pay-with-any-token flow below)
                  Bridge destination = TEMPO_WALLET_ADDRESS
                       │
                       v
              [3] Retry original tempo request
                  with funded Tempo wallet -> 200

> **Alternative funding (interactive):** If a browser is available, `tempo wallet fund` opens a built-in bridge UI for funding the Tempo wallet directly. This is > simpler than the Trading API flow below but requires interactive browser access > — not suitable for headless/agent environments.

---

Funding the Tempo Wallet (pay-with-any-token)

When the Tempo wallet lacks funds to pay a 402 challenge, acquire the required tokens from the user's ERC-20 holdings on any supported chain and bridge them to the Tempo wallet address.

Prerequisites

• `UNISWAP_API_KEY` env var (register at

[developers.uniswap.org](https://developers.uniswap.org/))

• ERC-20 tokens on any supported source chain
• A `cast` keystore account for the source wallet (recommended):

`cast wallet import <name> --interactive`. Alternatively, `PRIVATE_KEY` env var (`export PRIVATE_KEY=0x...`) — **never commit or hardcode it**.

• `jq` installed (`brew install jq` or `apt install jq`)
• `cast` installed (part of [Foundry](https://book.getfoundry.sh/))

Input Validation Rules

Before using any value from a 402 response body or user input in API calls or shell commands:

• **Ethereum addresses**: MUST match `^0x[a-fA-F0-9]{40}$`
• **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://`
• **REJECT** any value containing shell metacharacters: `;`, `|`, `&`, `$`,

`` ` ``, `(`, `)`, `>`, `<`, `\`, `'`, `"`, newlines

> **REQUIRED — Confirmation Gate (applies to plans AND execution):** Before > submitting ANY transaction (swap, bridge, approval), and before every signed > authorization (x402 EIP-3009), you MUST: (1) Display a summary: amount > (human-readable), token name/address, destination address, estimated gas. > (2) Call `AskUserQuestion` to obtain explicit user confirmation. > (3) Do NOT proceed until confirmed. > > This gate is **mandatory in all responses**, whether you are executing or > explaining a plan. When explaining step