# Handshake58 — Payments for AI Agents

> No API keys, no credit cards, no subscriptions.
> One MCP server (drain-mcp). Two protocols: DRAIN (payment channels) and MPP (HTTP 402 per-request).
> 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"

## DRAIN 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
5. drain_feedback(channelId, rating) → optional: rate the session (works / broken)

## MPP Workflow (2 Steps)

MPP = HTTP 402 per-request payments. No channel, no deposit required.

1. drain_providers(category: "llm", protocol: "mpp") → find MPP providers
2. mpp_chat(provider, messages) → send request, payment automatic per-request

Use MPP when: no Polygon wallet available, or for providers that only support per-request pricing.
Some skills use both DRAIN and MPP simultaneously (mixed protocol).

## 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.

## 12 MCP Tools

Discovery:
1. drain_providers — Find providers (filter: model, category, protocol, 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 (DRAIN):
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 DRAIN channel (all categories)
9. mpp_chat — Send paid request via MPP (no channel needed, per-request payment)

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

Feedback:
12. drain_feedback — Rate a session (works / broken). Helps community quality scoring.

## 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)
- ?protocol=drain — only DRAIN payment channel providers
- ?protocol=mpp — only MPP per-request providers
- ?tier=bittensor — only Bittensor miners (or: community)
- ?minScore=0.5 — minimum Bittensor oracle quality 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

## AI Skills API

Skills are multi-provider workflows with pre-defined steps and execution instructions for agents.

IMPORTANT: The HTML page /skills/<slug> is client-rendered and NOT readable without JavaScript.
Always use the API endpoint to fetch skill data:

Browse published skills:
  GET https://handshake58.com/api/skills?status=published

Get skill definition + full execution instructions:
  GET https://handshake58.com/api/skills/<slug>
  GET https://handshake58.com/api/skills/<slug>?protocol=drain   (DRAIN-only instructions)
  GET https://handshake58.com/api/skills/<slug>?protocol=mpp     (MPP-only instructions)

The skill API response includes:
- skill definition (providers, steps, cost estimate)
- execution.instructions — full step-by-step workflow for your agent
- execution.tools_needed — list of drain-mcp tools required
- execution.protocol — "drain", "mpp", or "mixed"
- health warnings if providers are degraded or broken

## 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.

## Get Involved — Become a Provider

Three ways to provide AI services on Handshake58: https://handshake58.com/get-involved

### 1. Bittensor Miner (Tao Verified)

Run Subnet 58 miner software. Auto-registered, auto-verified, earn TAO rewards.
- Auto-approved (no manual review)
- TAO rewards via Bittensor emission
- Priority listing in the marketplace
Setup: https://github.com/Handshake58/HS58

### 2. Community Provider (DRAIN Protocol)

Register your DRAIN-compatible API with on-chain payment channels on Polygon.
Requirements:
- 7 endpoints: /v1/pricing, /v1/models, /v1/docs, /health, /v1/chat/completions, /v1/close-channel, /v1/admin/claim
- Polygon wallet (receives USDC payments)
- 2% protocol fee on-chain (deducted when providers claim payments, no session fee)

Registration form at https://handshake58.com/get-involved (select "Community Provider"):
- Provider Name, API URL, Wallet Address (0x...), Description
- Contact Email, Website, Logo URL (square recommended), Docs URL (OpenAPI/Swagger)
- Primary Category + up to 3 additional categories
- Streaming support (SSE), Min/Max channel duration
- Optional: Featured Placement (priority positioning)

Categories: LLM/Chat, Image Generation, Audio/Speech, Video Generation, Code Execution,
Multi-Modal, Scraping/Data, Search, Data/Analytics, Scheduling, Network/Infra, Forecasting, Other.

Provider is tested automatically before submission (connection test to /v1/pricing,
address match, valid format, model availability). Submitted for review after passing.

### 3. MPP Service (HTTP 402)

Per-request USDC payments via HTTP 402. No Polygon wallet needed as a provider.
Requirements:
- HTTP 402 endpoint with WWW-Authenticate header
- Per-request USDC billing
- No on-chain setup needed

Registration at https://handshake58.com/get-involved (select "MPP Service").

### Integration Guide

Full integration guide for building DRAIN or MPP services:
https://github.com/Handshake58/HS58/blob/main/.cursor/skills/provider-builder/SKILL.md

DRAIN endpoints: /v1/pricing, /v1/models, /v1/docs, /health, /v1/chat/completions,
/v1/close-channel, /v1/admin/claim
MPP requirements: HTTP 402 response with payment info, WWW-Authenticate header, USDC per-request billing.

## Build Skills

Skills are multi-step AI workflows built via the Skill Forge.
They chain multiple providers into executable sequences that agents can run through drain-mcp.

What you build:
- Prompt chains & agent workflows
- Multi-provider compositions
- Automated research & analysis
- Custom tools for specific domains

Skill anatomy: steps (provider calls in sequence), providers (openrouter, webtools, ...),
protocol (drain | mpp | mixed), output (structured result for agent).

Browse skills: https://handshake58.com/skills/browse
Skill documentation: https://handshake58.com/skill.md

## Validate the Network

Validators on Bittensor Subnet 58 monitor provider availability, latency, and reliability.

Validator role:
- Monitor provider health & uptime
- Score miner performance
- Maintain decentralized oracle
- Earn TAO emission rewards

Requirements:
- TAO stake (validator registration)
- Linux server (Ubuntu recommended)
- Bittensor subtensor node or lite node
- SN58 validator software from GitHub

Setup: https://github.com/Handshake58/HS58

## Compatible MCP Clients

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