# Taskmarket Onchain API — MCP server (x402 / USDC on Base)

Remote **Model Context Protocol** server (Streamable HTTP JSON-RPC) that exposes paid
on-chain data tools to agents. Discovery is free (`initialize`, `ping`, `tools/list`);
each tool call returns [x402 v2](https://x402.org) payment terms and is settled in
**USDC on Base** — no accounts, no API keys, no signup.

- **MCP endpoint:** `https://wharf-overpower-recoil.ngrok-free.dev/mcp`
- **Transport:** Streamable HTTP, JSON-RPC 2.0, MCP protocol `2024-11-05`
- **Payment:** x402 v2, Base mainnet (`eip155:8453`), USDC
  `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, payTo
  `0xe43389bF0cCf7f3056e93b8B273Fa78c3Bb75Fb6`
- **Facilitator:** [PayAI](https://facilitator.payai.network) (free public facilitator)

## Tools

| Tool | Price | What it returns |
| --- | --- | --- |
| `verify_receipt` | **$0.02** | Verify a transfer against an expected recipient + amount → `MATCH` / `MISMATCH` with on-chain evidence. |
| `wallet_balance` | **$0.01** | Decoded native / USDC / any ERC-20 balance, pinned to one block, with explorer evidence. |
| `tx_status` | **$0.01** | Transaction status, block, timestamp, from/to, value, gas used, fee. |
| `address_activity` | **$0.02** | Recent ERC-20 transfers for an address, newest first, bounded window. |

Free methods: `initialize`, `ping`, `tools/list`, `notifications/initialized`, and
`GET /mcp` (human-readable info).

## Connect

Clients with native remote-MCP support (Claude Desktop, Cursor, Cline, Continue, …):

```json
{
  "mcpServers": {
    "taskmarket-onchain": {
      "url": "https://wharf-overpower-recoil.ngrok-free.dev/mcp"
    }
  }
}
```

Clients that only speak stdio can bridge with:
`npx -y mcp-remote https://wharf-overpower-recoil.ngrok-free.dev/mcp`

## Verify the handshake (free)

```bash
curl -sS https://wharf-overpower-recoil.ngrok-free.dev/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'ngrok-skip-browser-warning: 1' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```

Or run the included script (initialize + tools/list, no payment):

```bash
node examples/mcp-handshake.mjs
```

A `tools/call` without payment returns a structured `paymentRequired` payload with the
402 terms (`accepts`, `payTo`, amount, network, endpoint, how-to-pay steps). Send a paid
retry with the `Payment` header to get the data.

## Pay-per-call flow (x402 v2)

1. Send `tools/call` (or `POST` the matching HTTP route) → the server answers **402**
   with `PAYMENT-REQUIRED` (base64 JSON) + an `accepts` list.
2. Sign an EIP-3009 `transferWithAuthorization` for the amount to `payTo` on Base.
3. Retry with the `Payment` header; the PayAI facilitator verifies/settles and the tool
   returns the JSON result with explorer-checkable evidence.

Buyers need USDC on Base; the facilitator pays settlement gas, so no ETH is required.

## HTTP mirrors

The same four tools are available as plain x402 HTTP routes:

`POST /verify-receipt`, `POST /wallet-balance`, `POST /tx-status`,
`POST /address-activity` (query-param `GET` variants also answer the 402).

Free discovery: [`/health`](https://wharf-overpower-recoil.ngrok-free.dev/health),
[`/openapi.json`](https://wharf-overpower-recoil.ngrok-free.dev/openapi.json),
[`/.well-known/x402`](https://wharf-overpower-recoil.ngrok-free.dev/.well-known/x402).

## Notes

- The origin is a permanent ngrok static domain. Browser-like requests may see an ngrok
  interstitial; API clients are not affected. Add `ngrok-skip-browser-warning: 1` if needed.
- This repository is the public metadata/manifest home for the hosted server. The
  production implementation runs privately; the manifest lives in `server.json`.

## License

MIT — see [LICENSE](LICENSE).