update content and form

youssefea · youssefea · commit 1b54592aa82f · 2026-03-27T12:41:35.000Z
diff --git a/docs/ai-agents/index.mdx b/docs/ai-agents/index.mdx
@@ -12,6 +12,8 @@ Base gives your AI agent the tools to operate as an independent economic actor:
 
 ### High-level flow
 
+Here's how the agent you can build from these guides operates end-to-end — from wallet setup and identity registration to making authenticated, paid API requests using the x402 protocol.
+
 ```mermaid
 sequenceDiagram
     participant Agent
diff --git a/docs/ai-agents/payments/pay-for-services-with-x402.mdx b/docs/ai-agents/payments/pay-for-services-with-x402.mdx
@@ -38,26 +38,40 @@ Any agent with a funded wallet can pay for any x402-enabled API — no pre-exist
 
 ### CDP Agentic Wallet
 
-With the CDP Agentic Wallet skills installed, your agent handles x402 payments automatically:
+With the [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/) skills installed, your agent handles x402 payments automatically:
 
 ```bash Terminal
 npx skills add coinbase/agentic-wallet-skills
 ```
 
-Then ask your agent to discover and call a paid service:
+**Discover available services** using the [`search-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/search-for-service) skill:
+
+```bash Terminal
+npx awal@latest x402 bazaar search "weather forecast"
+```
+
+**Call a paid service** using the [`pay-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/pay-for-service) skill:
+
+```bash Terminal
+npx awal@latest x402 pay https://example.com/api/weather \
+  -X POST \
+  -d '{"query": "New York"}'
+```
+
+Or prompt your agent directly:
 
 ```text
 Find APIs for sentiment analysis
 Call that weather API and get the forecast for New York
 ```
 
-The `search-for-service` and `pay-for-service` skills handle discovery, payment, and retries.
+The [`search-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/search-for-service) and [`pay-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/pay-for-service) skills handle discovery, payment, and retries.
 
 [CDP Agentic Wallet skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills)
 
 ### Sponge Wallet
 
-Sponge Wallet has a built-in x402 proxy that discovers services and handles payment automatically:
+[Sponge Wallet](https://www.paysponge.com) has a built-in x402 proxy that discovers services and handles payment automatically:
 
 **Step 1 — Discover a service:**
 
@@ -92,19 +106,10 @@ curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \
   }'
 ```
 
-Sponge detects the `402`, pays in USDC from your wallet, and returns the API response.
+[Sponge Wallet](https://www.paysponge.com) detects the `402`, pays in USDC from your wallet, and returns the API response.
 
 [Sponge Wallet docs →](https://wallet.paysponge.com/skill.md)
 
-## Supported networks and tokens
-
-| Network | Token | Notes |
-|---------|-------|-------|
-| Base | USDC | Default — lowest fees |
-| Base Sepolia | USDC | Testnet |
-| Solana | USDC | Via CDP facilitator |
-| Polygon | USDC | Via CDP facilitator |
-
 ## Error handling and retries
 
 | Status | Meaning | What to do |
@@ -114,8 +119,21 @@ Sponge detects the `402`, pays in USDC from your wallet, and returns the API res
 | `408` | Payment timeout | Retry with same or higher payment |
 | `429` | Rate limit | Back off and retry after the indicated delay |
 
-The CDP Agentic Wallet `pay-for-service` skill and Sponge Wallet's x402 proxy handle retries automatically. If you're building a custom client, parse the `PAYMENT-REQUIRED` header, construct the signed payload, and retry with the `PAYMENT-SIGNATURE` header.
+The [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/) [`pay-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/pay-for-service) skill and [Sponge Wallet's](https://www.paysponge.com) x402 proxy handle retries automatically. If you're building a custom client, parse the `PAYMENT-REQUIRED` header, construct the signed payload, and retry with the `PAYMENT-SIGNATURE` header.
+
+<Note>
+  If you're using [Bankr](https://bankr.bot), no setup is required. Just prompt it directly:
+
+  ```text
+  Get the current ETH price from a paid data source
+  Find a weather API and get the forecast for New York
+  Get the token balances for 0xYourAddress on Base
+  ```
+
+  Bankr handles service discovery, payment, and data extraction automatically.
+</Note>
 
+## Video Tutorial
 <iframe
   className="w-full aspect-video rounded-xl"
   src="https://www.youtube.com/embed/b5Wx2NAeY2E?si=r1FumIsbGt6nAt29"
diff --git a/docs/ai-agents/quickstart/payments.mdx b/docs/ai-agents/quickstart/payments.mdx
@@ -72,7 +72,7 @@ Then authenticate:
 Sign in to my wallet with your@email.com
 ```
 
-Or use a Sponge Wallet with native x402 support — see [wallet setup](/ai-agents/setup/wallet-setup) for all options.
+Or use a [Sponge Wallet](https://www.paysponge.com) with native x402 support — see [wallet setup](/ai-agents/setup/wallet-setup) for all options.
 
 ## Make your first x402 payment
 
diff --git a/docs/ai-agents/quickstart/trading.mdx b/docs/ai-agents/quickstart/trading.mdx
@@ -64,7 +64,7 @@ install the bankr skill from https://github.com/BankrBot/skills
 
 Create a dedicated account at [bankr.bot](https://bankr.bot) and generate an API key at [bankr.bot/api](https://bankr.bot/api).
 
-For CDP Agentic Wallet or Sponge Wallet, see [wallet setup](/ai-agents/setup/wallet-setup).
+For [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/) or [Sponge Wallet](https://www.paysponge.com), see [wallet setup](/ai-agents/setup/wallet-setup).
 
 ## Execute a swap
 
diff --git a/docs/ai-agents/setup/agent-registration.mdx b/docs/ai-agents/setup/agent-registration.mdx
@@ -10,14 +10,6 @@ When your agent calls a service, how does that service know it's really your age
 
 <AgentRegistrationDemo />
 
-<iframe
-  className="w-full aspect-video rounded-xl"
-  src="https://www.youtube.com/embed/l387PXGnrgU?si=EM4IKT14ajFoYkNP"
-  title="Agent identity, verification, and auth"
-  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-  allowFullScreen
-></iframe>
-
 ## Why register?
 
 - **Discoverability** — other agents and services can find your agent by querying the public registry
@@ -171,6 +163,16 @@ if (result.success) {
 
 SIWA ships drop-in middleware for Express, Next.js, Hono, and Fastify. See the [SIWA documentation](https://siwa.id/docs) for framework-specific examples, replay protection, and x402 payment integration.
 
+## Video Tutorial
+
+<iframe
+  className="w-full aspect-video rounded-xl"
+  src="https://www.youtube.com/embed/l387PXGnrgU?si=EM4IKT14ajFoYkNP"
+  title="Agent identity, verification, and auth"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowFullScreen
+></iframe>
+
 ## Related
 
 <CardGroup cols={2}>
diff --git a/docs/ai-agents/trading/data-fetching.mdx b/docs/ai-agents/trading/data-fetching.mdx
@@ -14,73 +14,138 @@ x402 is well-suited for trading data: your agent pays per call in USDC, with no
 
 - **No API key management** — your agent pays on demand; no credentials to rotate or store securely
 - **Pay only for what you use** — no monthly subscription for data you might not always need
-- **Works across any wallet** — Sponge Wallet's x402 proxy, CDP Agentic Wallet skills, and `x402-axios` all handle payment automatically
+- **Works across any wallet** — [Sponge Wallet's](https://www.paysponge.com) x402 proxy, [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/) skills, and `x402-axios` all handle payment automatically
 - **Composable** — your agent can call multiple data providers in the same session, paying each separately
 
 ## Discovering x402-compatible endpoints
 
 x402-compatible services publish a discovery document at `/.well-known/x402.json`. You can also browse the Bazaar catalog for a curated list of x402 data providers.
 
-To discover a service with Sponge Wallet:
+<Tabs>
+  <Tab title="CDP Agentic Wallet">
+    Use the [`search-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/search-for-service) skill to search the x402 Bazaar:
 
-```bash Terminal
-curl "https://api.wallet.paysponge.com/api/discover?query=price+feed" \
-  -H "Authorization: Bearer $SPONGE_API_KEY" \
-  -H "Sponge-Version: 0.2.1"
-```
+    ```bash Terminal
+    npx awal@latest x402 bazaar search "price feed"
+    ```
+
+    To browse all available resources:
+
+    ```bash Terminal
+    npx awal@latest x402 bazaar list --network base
+    ```
+  </Tab>
+  <Tab title="Sponge Wallet">
+    ```bash Terminal
+    curl "https://api.wallet.paysponge.com/api/discover?query=price+feed" \
+      -H "Authorization: Bearer $SPONGE_API_KEY" \
+      -H "Sponge-Version: 0.2.1"
+    ```
+  </Tab>
+</Tabs>
 
-## Curated x402 data sources
+## Example x402 data sources
 
 ### CoinGecko — price feeds
 
 CoinGecko provides cryptocurrency price feeds, market cap data, and historical OHLCV via x402-enabled endpoints.
 
 Fetch the current ETH price:
 
-```bash Terminal
-curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \
-  -H "Authorization: Bearer $SPONGE_API_KEY" \
-  -H "Sponge-Version: 0.2.1" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd",
-    "method": "GET",
-    "preferred_chain": "base"
-  }'
-```
+<Tabs>
+  <Tab title="CDP Agentic Wallet">
+    Use the [`pay-for-service`](https://docs.cdp.coinbase.com/agentic-wallet/skills/pay-for-service) skill:
+
+    ```bash Terminal
+    npx awal@latest x402 pay "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd"
+    ```
+  </Tab>
+  <Tab title="Sponge Wallet">
+    ```bash Terminal
+    curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \
+      -H "Authorization: Bearer $SPONGE_API_KEY" \
+      -H "Sponge-Version: 0.2.1" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "url": "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd",
+        "method": "GET",
+        "preferred_chain": "base"
+      }'
+    ```
+  </Tab>
+</Tabs>
 
-Or use the CDP Agentic Wallet `pay-for-service` skill:
+### Alchemy — onchain data
 
-```text
-Get the current ETH price from CoinGecko
-```
+Alchemy exposes enhanced APIs for onchain data — token balances, NFT metadata, mempool visibility, and decoded transaction history — via their [Agentic Gateway](https://github.com/alchemyplatform/skills/tree/main/skills/agentic-gateway) at `https://x402.alchemy.com`.
 
-### Alchemy — onchain data
+<Note>
+  Alchemy's x402 gateway uses SIWE wallet authentication via their own [`@alchemy/x402`](https://github.com/alchemyplatform/skills/tree/main/skills/agentic-gateway) CLI — not a generic x402 bazaar endpoint. Follow the setup steps below before making requests.
+</Note>
 
-Alchemy exposes enhanced APIs for onchain data — token balances, NFT metadata, mempool visibility, and decoded transaction history — via x402-gated endpoints.
+**Step 1 — Install and set up a wallet:**
+
+```bash Terminal
+npx @alchemy/x402 wallet generate
+```
 
-Fetch token balances for a wallet:
+**Step 2 — Generate a SIWE auth token:**
 
 ```bash Terminal
-curl -X POST "https://api.wallet.paysponge.com/api/x402/fetch" \
-  -H "Authorization: Bearer $SPONGE_API_KEY" \
-  -H "Sponge-Version: 0.2.1" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "https://base-mainnet.g.alchemy.com/v2/getTokenBalances",
-    "method": "POST",
-    "body": { "address": "0xYourAddress" },
-    "preferred_chain": "base"
-  }'
+npx @alchemy/x402 sign --private-key ./wallet-key.txt > siwe-token.txt
 ```
 
-### Nansen — wallet analytics
+**Step 3 — Fetch token balances on Base:**
+
+<Tabs>
+  <Tab title="Token balances (JSON-RPC)">
+    ```bash Terminal
+    TOKEN=$(cat siwe-token.txt)
+
+    curl -s -X POST "https://x402.alchemy.com/base-mainnet/v2" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: SIWE $TOKEN" \
+      -d '{
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "alchemy_getTokenBalances",
+        "params": ["0xYourAddress"]
+      }'
+    ```
+  </Tab>
+  <Tab title="Portfolio (multi-chain)">
+    ```bash Terminal
+    TOKEN=$(cat siwe-token.txt)
+
+    curl -s -X POST "https://x402.alchemy.com/data/v1/assets/tokens/by-address" \
+      -H "Content-Type: application/json" \
+      -H "Authorization: SIWE $TOKEN" \
+      -d '{"addresses": ["0xYourAddress"], "withMetadata": true}'
+    ```
+  </Tab>
+  <Tab title="Token prices">
+    ```bash Terminal
+    TOKEN=$(cat siwe-token.txt)
+
+    curl -s -G "https://x402.alchemy.com/prices/v1/tokens/by-symbol" \
+      --data-urlencode "symbols=ETH" \
+      --data-urlencode "symbols=USDC" \
+      -H "Authorization: SIWE $TOKEN"
+    ```
+  </Tab>
+</Tabs>
+
+If the gateway returns `402`, handle payment with the CLI and retry:
+
+```bash Terminal
+PAYMENT_SIG=$(npx @alchemy/x402 pay --private-key ./wallet-key.txt --payment-required "$PAYMENT_REQUIRED")
+```
 
-Nansen provides wallet labeling, smart money flow analysis, and on-chain fund tracking. x402 endpoint availability is expanding — check [nansen.ai](https://nansen.ai) for current endpoint status.
+See the full [Alchemy Agentic Gateway skill](https://github.com/alchemyplatform/skills/tree/main/skills/agentic-gateway) for wallet bootstrap, payment handling, and SDK integration.
 
 ## Making data calls inside an OpenClaw agent
 
-Install the Sponge Wallet skill or CDP Agentic Wallet skills, then prompt your agent directly:
+Install the [Sponge Wallet](https://www.paysponge.com) skill or [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/) skills, then prompt your agent directly:
 
 ```text
 Get the current prices of ETH, BTC, and SOL from a paid data source
diff --git a/docs/ai-agents/trading/trade-execution.mdx b/docs/ai-agents/trading/trade-execution.mdx
@@ -12,23 +12,23 @@ Base offers two structural advantages for trading agents: **Flashblocks** (200ms
 
 ## Executing swaps with wallet-native tools
 
-Bankr, CDP Agentic Wallet, and Sponge Wallet all include built-in swap capabilities — no external DEX integration needed.
+[Bankr](https://bankr.bot), [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/), and [Sponge Wallet](https://www.paysponge.com) all include built-in swap capabilities — no external DEX integration needed.
 
-With Bankr:
+With [Bankr](https://bankr.bot):
 
 ```text
 Buy $50 of ETH on Base
 Swap 100 USDC for ETH at market price
 ```
 
-With CDP Agentic Wallet skills:
+With [CDP Agentic Wallet](https://docs.cdp.coinbase.com/agentic-wallet/) skills:
 
 ```text
 Buy $50 of ETH
 Trade 0.01 ETH for USDC
 ```
 
-With Sponge Wallet:
+With [Sponge Wallet](https://www.paysponge.com):
 
 ```bash Terminal
 curl -X POST "https://api.wallet.paysponge.com/api/swap" \
