> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tazpal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Wallet Setup

> Set up an x402 wallet to pay for X1-BaaS requests — no account needed.

# x402 Wallet Setup

x402 lets AI agents pay per request with USDC on Base — no accounts, no sign-up, no monthly commitment. This guide walks you through setting up a wallet for your agent.

<Note>
  **Already have an x402 wallet?** Skip to [Making your first paid request](#making-your-first-paid-request).
</Note>

## What is x402?

x402 is an open payment standard built on HTTP. When your agent requests a protected resource, the server responds with `402 Payment Required` and a price. Your agent signs a USDC payment and retries — the whole flow happens in the request/response cycle, no separate checkout.

| Feature             | x402               | Traditional API keys   |
| ------------------- | ------------------ | ---------------------- |
| Account required    | ❌ No               | ✅ Yes                  |
| Signup flow         | ❌ None             | ✅ Email + billing      |
| Payment method      | USDC on Base       | Credit card            |
| Per-request billing | ✅ Automatic        | ⚠️ Prepaid credits     |
| Agent-native        | ✅ Built for agents | ⚠️ Designed for humans |

## Choose your setup path

Pick the path that matches your agent platform:

<CardGroup cols={2}>
  <Card title="Agentic Wallet MCP" icon="plug" href="#agentic-wallet-mcp">
    For Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini CLI, or any MCP client. **Easiest path.**
  </Card>

  <Card title="Agentic Wallet CLI" icon="terminal" href="#agentic-wallet-cli">
    For agents that can run shell commands but don't speak MCP. **Fastest setup.**
  </Card>

  <Card title="CDP SDK" icon="code" href="#cdp-sdk">
    For custom Python or TypeScript agents. **Most control.**
  </Card>

  <Card title="OpenClaw" icon="robot" href="#openclaw">
    For OpenClaw agents with existing x402 support.
  </Card>
</CardGroup>

***

## Agentic Wallet MCP

**Best for:** Claude Desktop, Claude Code, Cursor, Codex CLI, Gemini CLI, and any MCP-compatible client.

**Setup time:** \~5 minutes

### 1. Install the MCP server

```bash theme={null}
npx @coinbase/payments-mcp
```

The installer will prompt you to select your MCP client and configure it automatically.

### 2. Restart your client

Close and reopen your MCP client to load the wallet tools.

### 3. Sign into your wallet

Ask your agent:

```
Show me my wallet
```

This opens a browser window for authentication:

* **New users:** Enter your email → verify your email → wallet created
* **Returning users:** Enter your email → verify your email → you're in

### 4. Fund your wallet

In the wallet UI:

1. Click **Fund**
2. Follow the Coinbase Onramp flow to add USDC
3. Return to your agent

Or:

1. Click **Receive**
2. Copy your wallet address
3. Send USDC on Base to that address

<Tip>
  **How much to fund?** At $0.005/request, $1 USDC covers 200 scrapes. Start with \$5 for 1,000 requests.
</Tip>

### 5. Set spending limits (recommended)

In the wallet UI:

1. Click the spending limit tracker
2. Set **Max per call:** e.g., \$0.05
3. Set **Max per session:** e.g., \$5.00
4. Save

Your agent respects these limits but can't change them — only you can.

### 6. Make your first paid request

Ask your agent:

```
Scrape https://example.com using X1-BaaS
```

Or search for X1-BaaS in the Bazaar:

```
What x402 services are available for web scraping?
```

***

## Agentic Wallet CLI

**Best for:** Agents that can run shell commands, CI pipelines, terminal-based workflows.

**Setup time:** \~2 minutes

### 1. Install and authenticate

```bash theme={null}
# Send OTP to your email
npx awal auth login your@email.com

# Verify with the 6-digit code
npx awal auth verify <flowId> <otp>

# Confirm authentication
npx awal status
```

### 2. Get your wallet address

```bash theme={null}
npx awal address
```

Send USDC on Base to this address.

### 3. Check your balance

```bash theme={null}
npx awal balance
```

### 4. Make a paid request

```bash theme={null}
npx awal x402 pay https://api.tazpal.com/v1/scrape \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

### CLI Reference

| Command                               | Purpose            |
| ------------------------------------- | ------------------ |
| `npx awal status`                     | Check auth status  |
| `npx awal balance`                    | Check USDC balance |
| `npx awal address`                    | Get wallet address |
| `npx awal send <amount> <recipient>`  | Send USDC          |
| `npx awal x402 bazaar search <query>` | Discover services  |
| `npx awal x402 pay <url>`             | Make paid request  |

***

## CDP SDK

**Best for:** Custom Python or TypeScript agents, applications with their own payment logic.

**Setup time:** \~15 minutes

### Prerequisites

1. Create a free account at [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com)
2. Generate an API key and wallet secret
3. Set environment variables:

```bash theme={null}
export CDP_API_KEY_ID="your-api-key-id"
export CDP_API_KEY_SECRET="your-api-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"
```

### TypeScript

```bash theme={null}
npm install @coinbase/cdp-sdk @x402/core @x402/evm @x402/fetch
```

```typescript theme={null}
import { CdpX402Client } from "@coinbase/cdp-sdk/x402";
import { wrapFetchWithPayment } from "@x402/fetch";

const client = new CdpX402Client();
const { evmAddress } = await client.getAddresses();
console.log(`Paying from ${evmAddress}`);

const fetchWithPayment = wrapFetchWithPayment(globalThis.fetch, client);
const response = await fetchWithPayment("https://api.tazpal.com/v1/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com" }),
});

console.log(`HTTP ${response.status}`);
```

### Python

```bash theme={null}
pip install "cdp-sdk" "x402[evm,httpx]"
```

```python theme={null}
import asyncio
from cdp import CdpClient
from cdp.evm_local_account import EvmLocalAccount
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact import ExactEvmScheme

async def main():
    async with CdpClient() as cdp:
        account = await cdp.evm.get_or_create_account(name="baas-client")
        signer = EthAccountSigner(EvmLocalAccount(account))
        print(f"Paying from {signer.address}")

        payment_client = x402Client()
        payment_client.register("eip155:8453", ExactEvmScheme(signer))

        async with x402HttpxClient(payment_client) as http:
            response = await http.post(
                "https://api.tazpal.com/v1/scrape",
                json={"url": "https://example.com"},
            )
            print(f"HTTP {response.status_code}")

asyncio.run(main())
```

### Fund the wallet

The wallet address is printed when you run the client. Send USDC on Base to that address.

For testing, use Base Sepolia testnet and the [CDP Faucet](https://docs.cdp.coinbase.com/faucets/introduction/quickstart).

***

## OpenClaw

OpenClaw agents with x402 support can use X1-BaaS directly. The MCP server handles payment automatically.

### MCP Configuration

Add to your OpenClaw MCP configuration:

```json theme={null}
{
  "x1-baas": {
    "url": "https://api.tazpal.com/mcp",
    "transport": "streamable-http"
  }
}
```

### Using the scrape tool

Once configured, your agent can call the `scrape` tool directly. If x402 payment is required, the agent will handle the payment flow automatically (if it has an x402 wallet configured).

***

## Hermes Agent

Hermes Agent by Nous Research supports MCP servers natively via `~/.hermes/config.yaml`.

### MCP Configuration

Add to `~/.hermes/config.yaml`:

```yaml theme={null}
mcp_servers:
  x1-baas:
    url: https://api.tazpal.com/mcp
    transport: streamable-http
```

Or use the interactive MCP picker:

```bash theme={null}
hermes mcp
```

### Setting up x402 payments

Hermes Agent can use the Agentic Wallet MCP for x402 payments:

```bash theme={null}
npx @coinbase/payments-mcp
```

Select "Other" when prompted for your client, then add the MCP server to your Hermes config:

```yaml theme={null}
mcp_servers:
  x1-baas:
    url: https://api.tazpal.com/mcp
    transport: streamable-http
  payments:
    command: "npx"
    args: ["@coinbase/payments-mcp"]
```

Alternatively, use the CLI path with `npx awal` (see [Agentic Wallet CLI](#agentic-wallet-cli) above).

### Using the scrape tool

Once configured, ask Hermes to scrape a page:

```
Scrape https://news.ycombinator.com using X1-BaaS
```

Hermes will discover the MCP tools and use them automatically.

***

## Making your first paid request

Once your wallet is set up and funded:

### Via MCP (any client)

```
Scrape https://news.ycombinator.com using X1-BaaS
```

### Via curl

```bash theme={null}
curl -X POST https://api.tazpal.com/v1/scrape \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded-payment>" \
  -d '{"url": "https://news.ycombinator.com"}'
```

### Via the BaaS API directly

The x402 flow is automatic when using the CDP SDK or Agentic Wallet:

1. Agent requests `/v1/scrape` with no payment
2. Server responds `402 Payment Required` with price and payment options
3. Agent signs a USDC permit and retries with `X-PAYMENT` header
4. Server verifies payment, scrapes the page, returns clean Markdown

<Note>
  **You're only charged on success.** Payment is verified before the scrape and settled only after a successful result. Timeouts and connection failures never charge you.
</Note>

***

## Troubleshooting

### "402 Payment Required" on every request

Your wallet doesn't have enough USDC. Check your balance:

* MCP: Ask "What's my wallet balance?"
* CLI: `npx awal balance`
* SDK: Check the wallet address and verify on [BaseScan](https://basescan.org)

### "Authentication failed" after setting up wallet

Your payment may have expired. x402 payments have a time window — if your agent takes too long between signing and sending, the payment expires. This is normal; just retry.

### Wallet not showing up

Make sure you:

1. Completed email verification
2. Restarted your MCP client after installation
3. Asked your agent to "Show me my wallet" (this triggers the auth flow)

### Can I use testnet?

Yes. For development:

* CDP SDK: Pass `environment: "development"` to use Base Sepolia
* Get test USDC from the [CDP Faucet](https://docs.cdp.coinbase.com/faucets/introduction/quickstart)
* X1-BaaS testnet endpoint: `https://api-testnet.tazpal.com` (coming soon)

***

## Security Best Practices

1. **Set spending limits** — Always configure max per-call and per-session limits in the wallet UI
2. **Use separate wallets** — Don't reuse your main crypto wallet for agent payments
3. **Monitor usage** — Check your wallet balance and transaction history regularly
4. **Start small** — Fund with \$5-10 USDC initially, increase as needed
5. **Use testnet first** — Test your integration on Base Sepolia before mainnet

***

## What to read next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    API keys vs x402 — choose the right path for your use case.
  </Card>

  <Card title="Scrape endpoint" icon="globe" href="/endpoints/scrape">
    Full API reference for the scrape endpoint.
  </Card>

  <Card title="x402 Protocol" icon="bolt" href="https://docs.cdp.coinbase.com/x402/how-it-works">
    Learn how x402 payments work under the hood.
  </Card>

  <Card title="Agentic Wallet Docs" icon="wallet" href="https://docs.cdp.coinbase.com/agentic-wallet/mcp/quickstart">
    Official Coinbase Agentic Wallet documentation.
  </Card>
</CardGroup>