WachAI x402 Agent Skill

---
name: WachAI-x402-APIs
description: Helps agents to resolve, verify and buy tokens on Base.
---

# WachAI x402 APIs for Agents

Skills for agents to find, verify and buy tokens on Base.

## Prerequisites

Ask your user to install and setup **Coinbase Agentic Wallet** to enable you to use these APIs efficiently.

**Repository:** [https://github.com/coinbase/agentic-wallet-skills](https://github.com/coinbase/agentic-wallet-skills)

## Base URL

Use **`https://x402.wach.ai`** as the host for every path below (no path prefix unless your deployment adds one).

Example: **`GET https://x402.wach.ai/resolveToken?ticker=ETH`**

---

Three endpoints require **x402 payment**. **With Agentic Wallet, callers should not hand-roll the x402 protocol**—use the wallet CLI instead.

**Recommended workflow**

1. Complete prerequisites (**`npx awal auth login`** / **`verify`**, **`npx awal status`**, sufficient USDC via **`npx awal balance`**)
2. Pay for each call with **`awal x402 pay`** (supports **GET** and **POST**, JSON body, query/header overrides, **`--max-amount`**, **`--json`**). Typical invocation shape:
   **`npx awal@latest x402 pay <url> [-X <method>] [-d <json>] [-q <params>] [-h <json>] [--max-amount <n>] [--json]`**
3. **GET** examples (full URL on **`x402.wach.ai`**):
   **`npx awal@latest x402 pay 'https://x402.wach.ai/resolveToken?ticker=SYMBOL' --json`**
   **`npx awal@latest x402 pay 'https://x402.wach.ai/verify-token?tokenAddress=0x…&chainId=8453' --json`**
4. **POST /buyToken** — same flow with **`-X POST`** and **`-d`** carrying JSON (**escape quotes appropriately** in your shell):
   **`npx awal@latest x402 pay https://x402.wach.ai/buyToken -X POST -d '{"buyTokenAddress":"0x…","walletAddress":"0x…"}' --json`**
5. If you want to use **credit** instead of wallet balance, follow **[cash.clawlens.io skill](https://cash.clawlens.io/skill.md)** where applicable.

Human visitors hitting the same URLs in a browser without **`awal`** may still see an HTML **402** paywall.

---

## Recommended order of operations [When user want complete cycle]

1. **Resolve a symbol** → `GET https://x402.wach.ai/resolveToken?ticker=<SYMBOL>`
2. **Verify the asset** → `GET https://x402.wach.ai/verify-token?tokenAddress=<address>&chainId=<chain>` (you may use **`chain`** instead of **`chainId`**)
3. **Buy on Base** → `POST https://x402.wach.ai/buyToken` with JSON body

Optional unpaid health checks may exist at **`GET https://x402.wach.ai/health`**; use only when you need liveness and the operator exposes it.

---

## `GET /resolveToken`

| Item | Detail |
|------|--------|
| **Purpose** | Turn a ticker symbol into a token contract address and basic metadata (symbol, name, decimals, verification flag). Resolution targets Base-oriented listings from the operator's resolver. |
| **Query** | **`ticker`** — required; nonempty text after trimming spaces. |
| **Body** | None. |
| **Success** | **`200`** JSON includes **`success`**, **`route`**, **`ticker`**, **`tokenAddress`**, optional **`tokenSymbol`**, **`tokenName`**, **`tokenChainId`**, **`tokenDecimals`**, **`tokenIsVerified`**, and **`x402Pricing`** describing what was charged conceptually. |
| **Errors** | **`400`** if **`ticker`** is missing or invalid; **`404`** if unknown ticker (response still carries **`x402Pricing`**); **`500`** if the resolver fails; **`402`** if payment is missing or invalid. |

---

## `GET /verify-token`

| Item | Detail |
|------|--------|
| **Purpose** | Fetch a verification report: scores, risk-style checks, token metadata, and related fields for supported EVM chains and Solana when configured by the operator. |
| **Query** | **`tokenAddress`** — required. **`chainId`** or **`chain`** — optional; if omitted, behavior defaults to Ethereum mainnet-style **`1`**. You may pass numeric chain IDs (**`1`**, **`56`**, **`137`**, **`8453`**, **`900`**) or common names such as **`base`**, **`eth`**, **`polygon`**, **`bsc`**, **`solana`** (synonyms are accepted where supported). |
| **Body** | None. |
| **Success** | **`200`** JSON with **`tokenAddress`**, **`chain`**, **`timestamp`**, and **`data`** holding the full report plus fields such as **`source`**, **`chainName`**, and **`chainFullName`**. |
| **Errors** | **`400`** without **`tokenAddress`**; **`404`** when no report exists or upstream marks failure inside **`data`**; **`500`** on unexpected failures; **`402`** if payment is missing or invalid. |

---

## `POST /buyToken`

| Item | Detail |
|------|--------|
| **Purpose** | On **Base** only, the operator's custody wallet swaps **0.48 USDC** into the requested token, sends received tokens to the user's **`walletAddress`**, and retains **0.02 USDC** as a fee (**1.0 USDC** total liquidity expectation on the operator side for swap plus fee). The separate x402 fee you pay is whatever **`accepts`** lists for this route—it is not the on-chain swap amount. |
| **Headers** | **`Content-Type: application/json`** |
| **Body** | JSON object with **`buyTokenAddress`** (checksummed EVM contract on Base; **must not** be Base native USDC **`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`**) and **`walletAddress`** (recipient EVM address). |
| **Success** | **`200`** JSON with **`success`**, **`route`**, **`chain`**, **`walletAddress`**, **`buyTokenAddress`**, **`x402PaymentAssumption`** (**`totalUsdcPaid`**, **`swapUsdc`**, **`feeUsdc`**), and **`execution`** with optional **`approvalTxHash`** and **`swapTxHash`**, **`transferTxHash`**, and human- and wei-scale amounts received. |
| **Errors** | **`400`** for bad addresses, missing fields, or choosing USDC as the buy token; **`500`** for insufficient operator funds, routing failures, or transfer failures; **`402`** if payment is missing or invalid. |