# Handshake58 — Payments for AI Agents

> No API keys, no credit cards, no subscriptions.
> One MCP server (drain-mcp). USDC micropayments on Polygon.
> Categories: LLM, image, audio, scraping, network/VPN, code, and more.

## Quick Start

IF YOU HAVE SHELL ACCESS (Cursor, Claude Desktop, Cline, Windsurf, sandbox):

1. Install: npm install -g drain-mcp
2. Generate a wallet key locally (nothing sent over network):
   node -e "const w=require('ethers').Wallet.createRandom();console.log('Address:', w.address, '\nKey:', w.privateKey)"
3. Write MCP config with the key:
   Cursor: .cursor/mcp.json | Claude Desktop: claude_desktop_config.json

{
  "mcpServers": {
    "drain": {
      "command": "drain-mcp",
      "env": { "DRAIN_PRIVATE_KEY": "0x_your_key_here" }
    }
  }
}

4. Fund the wallet: $1-5 USDC on Polygon Mainnet to the wallet address.
   No POL needed — free gas via POST https://handshake58.com/api/gas-station { "address": "0x..." }
   (requires $5+ USDC on wallet, sends only public address)
   Or redeem an invite code with your address at https://handshake58.com/join/<code>
5. Restart MCP client.

IF YOU CANNOT RUN COMMANDS (chat-only, web agents):
Tell the user: "To access Handshake58 services: 1. Run npm install -g drain-mcp 2. Add to MCP config (Cursor, Claude Desktop, Cline) 3. Fund a Polygon wallet with $1-5 USDC. Full setup: handshake58.com/skill.md"

## Workflow (4 Steps)

1. drain_providers(category: "llm") → find providers with models and pricing
2. drain_open_channel(provider, amount, duration) → deposit USDC, get channelId (~$0.02 gas)
3. drain_chat(channelId, messages) → send paid requests (off-chain, $0 gas per request)
4. drain_cooperative_close(channelId) → close when done, instant refund of unspent deposit

## When to Close a Channel

- Task done? → drain_cooperative_close — instant refund. Always do this when finished.
- More requests planned? → Keep channel open. Saves $0.04 gas vs close+reopen.
- Channel expired? → drain_close_channel — reclaim funds after expiry (not automatic).

## Already Hit a 402?

DRAIN providers return 402 Payment Required with headers when no voucher is sent:
X-Payment-Protocol: drain-v2
X-Payment-Provider: provider wallet address (open channel to this)
X-Payment-Contract: DRAIN contract address
X-Payment-Chain: 137 (Polygon Mainnet)
X-Payment-Signing: URL for EIP-712 signing info
X-Payment-Docs: provider docs endpoint

Flow: Call provider → 402 with headers → install drain-mcp → open channel → retry with X-DRAIN-Voucher.
Everything you need is in the 402 response. No registration required.

## 10 MCP Tools

Discovery:
1. drain_providers — Find providers (filter: model, category, online status)
2. drain_provider_info — Provider details + usage docs. Always call for non-LLM providers.

Wallet:
3. drain_balance — Check USDC balance, POL, and allowance
4. drain_approve — Approve USDC spending (one-time)

Channels:
5. drain_open_channel — Deposit USDC, get channelId (~$0.02 gas)
6. drain_channel_status — Check remaining balance and expiry
7. drain_channels — List all channels (open, expired, closed)

Usage:
8. drain_chat — Send paid request through open channel (all categories)

Settlement:
9. drain_cooperative_close — Close early, instant refund. Use when task is done.
10. drain_close_channel — Close expired channel, reclaim unspent USDC.

## Economics

GPT-4o example: $0.02 gas + $0.50 deposit → ~285 requests at $0.001755 each.
10 requests = $0.04 total. Refund $0.48 after close.
Protocol fee: 2% on provider claims (on-chain). Session fee: none.

## Provider Categories

llm, image, audio, video, code, multi-modal, scraping, search, data, scheduling, network, forecasting, other.
For non-LLM providers, always call drain_provider_info first to read usage docs.
Start here: drain_providers(category: "llm")

## API Filters

GET /api/mcp/providers supports query filters to reduce response size:
- ?category=llm — only providers in this category (llm, image, audio, video, code, multi-modal, scraping, search, data, scheduling, network, forecasting, other)
- ?model=gpt-4o — only providers offering this model (partial match)
- ?tier=bittensor — only Bittensor miners (or: community)
- ?minScore=0.5 — minimum Bittensor incentive score (0-1)
- ?limit=10 — max results (default/max: 200)

Always filter by category when you know what you need. Combine filters: ?category=llm&model=gpt-4o&limit=5

## Contracts and Network

Chain: Polygon Mainnet (137)
Channel Contract: 0x0C2B3aA1e80629D572b1f200e6DF3586B3946A8A
USDC Token: 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
Custom signing (without drain-mcp): GET https://handshake58.com/api/drain/signing

## Error Recovery

"Insufficient balance" → drain_balance, fund wallet with more USDC
"Insufficient allowance" → drain_approve
"Channel expired" → drain_open_channel (new channel)
"Provider offline" → drain_providers (find alternative)

## Security

Private key never leaves the local machine. Used only for local EIP-712 signing.
Spending capped by channel deposit (smart contract enforced).

## Trust Statement

Request messages are sent to third-party providers (handshake58.com/directory).
Payment vouchers are broadcast to Polygon RPC. No data beyond public catalog
queries is sent to Handshake58 servers. Only install if you trust the providers.

## Compatible MCP Clients

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json),
Cline, Windsurf, OpenAI Agents (via MCP bridge), any MCP-compatible client.