Toll-metered agent economy

Agent Developer Portal

Build AI agents that use ARC-Relay's email infrastructure. Register an agent, get an API key, and make toll-metered MCP calls — starting with $1.00 free.

Quick Start

Step 1

Register your agent

POST to /api/v1/agents/register with a name. You'll get an API key and a wallet with $1.00.

Step 2

Save your API key

Your key starts with ar_agent_. Pass it as a Bearer token or X-Api-Key header.

Step 3

Make your first call

Hit POST /mcp with a JSON-RPC 2.0 tools/call. Each call costs $0.0001.

terminal 
# 1. Register your agent
curl -X POST https://arc-relay.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "Email health checker"}'

# Response:
# {
#   "agent_id": "ext_my-agent",
#   "api_key": "ar_agent_my-agent_a1b2c3d4e5f6...",
#   "wallet_id": "w_1a2b3c4d5e6f7890",
#   "balance_usd": 1.0
# }

# 2. Make an MCP tool call ($0.0001 per call)
curl -X POST https://arc-relay.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ar_agent_my-agent_a1b2c3d4e5f6..." \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "check_email_health",
      "arguments": {"domain": "gmail.com"}
    }
  }'

# 3. Check your balance
curl https://arc-relay.com/api/v1/wallet \
  -H "Authorization: Bearer ar_agent_my-agent_a1b2c3d4e5f6..."

# { "balance_usd": 0.9999, "total_spent": 0.0001, ... }

Authentication

Agent API keys use the ar_agent_ prefix. Pass them via either header:

Headers 
# Option A: Authorization header
Authorization: Bearer ar_agent_my-agent_a1b2c3d4e5f6...

# Option B: X-Api-Key header
X-Api-Key: ar_agent_my-agent_a1b2c3d4e5f6...
Agent keys vs user keys: Agent keys (ar_agent_) are for the toll protocol and agent economy — they get metered wallets. User keys (ar_live_) are for managing your personal ARC-Relay account and use quota-based billing instead.

Rate Schedule

Operation Rate Key Price (USD)
MCP Tool Call mcp_call $0.0001
Email Forward email_forward $0.0002
REST API Call rest_api $0.00005
Agent-to-Agent Invoke agent_invoke $0.0003

New agents start with a $1.00 default balance — enough for 10,000 MCP calls. Rates are returned live from GET /api/v1/toll/rates.

Registration

POST /api/v1/agents/register Public

Register a new agent. Creates a wallet with $1.00 default balance and returns an API key.

Request Body
JSON 
{
  "name": "my-agent",            // required, 2+ chars
  "description": "Email triage", // optional
  "capabilities": ["email"]      // optional array
}
Response 201
{
  "agent_id": "ext_my-agent",
  "api_key": "ar_agent_my-agent_a1b2c3d4e5f67890abcdef1234567890",
  "wallet_id": "w_1a2b3c4d5e6f7890",
  "balance_usd": 1.0
}
GET /api/v1/agents/me Authenticated

Retrieve the authenticated agent's profile and wallet summary.

Response 200
{
  "agent_id": "ext_my-agent",
  "wallet_id": "w_1a2b3c4d5e6f7890",
  "balance_usd": 0.95,
  "total_deposited": 1.0,
  "total_spent": 0.05,
  "description": "Email triage",
  "capabilities": ["email"]
}
GET /api/v1/agents Public

Public directory of registered agents. Returns up to 50 most recent.

Response 200
{
  "agents": [
    {
      "agent_id": "ext_my-agent",
      "description": "Email triage",
      "capabilities": ["email"],
      "created_at": "2026-03-10T04:49:00.000Z"
    }
  ]
}

Wallet

GET /api/v1/wallet Authenticated

Current balance and last 20 transactions.

Response 200
{
  "wallet_id": "w_1a2b3c4d5e6f7890",
  "balance_usd": 0.999,
  "total_deposited": 1.0,
  "total_spent": 0.0001,
  "transactions": [
    {
      "tx_id": "tx_ef519d790e72887b",
      "type": "toll",
      "from_wallet": "w_1a2b3c4d5e6f7890",
      "to_wallet": null,
      "amount_usd": 0.0001,
      "api_call_name": "mcp:check_email_health",
      "description": "Toll for mcp:check_email_health",
      "created_at": "2026-03-10T04:49:45.898Z"
    }
  ]
}
POST /api/v1/wallet/deposit Authenticated

Add funds to your agent wallet. Immediate credit, no invoice.

Request Body
{
  "amount": 5.00   // positive number, USD
}
Response 200
{
  "balance_usd": 5.999
}
POST /api/v1/wallet/deposit/solana Authenticated Solana USDC

Verify an on-chain Solana USDC payment and credit your wallet. Send USDC to the receiver address from a 402 response, then submit the transaction signature here.

Request Body
{
  "signature": "5UfD...base58...txSig",  // Solana tx signature (87-88 chars)
  "invoice_id": "inv_e7e72df3a84a1406"   // optional, from 402 response
}
Response 200
{
  "success": true,
  "amount_usd": 5.0,
  "balance_usd": 6.0,
  "signature": "5UfD...txSig",
  "invoice_id": "inv_e7e72df3a84a1406"
}
Error Responses
404 Transaction not found (not confirmed yet — wait and retry)
409 Transaction already processed (already credited)
422 Transaction failed on-chain or no USDC transfer to receiver
502 Solana RPC unreachable (retry shortly)
Flow
# 1. Get 402 with Solana payment info
# (MCP call or REST call returns solana_usdc.receiver + memo)

# 2. Send USDC on Solana to the receiver address
# (use any Solana wallet or SDK)

# 3. Submit tx signature to verify and credit
curl -X POST https://arc-relay.com/api/v1/wallet/deposit/solana \
  -H "Authorization: Bearer ar_agent_my-agent_..." \
  -H "Content-Type: application/json" \
  -d '{"signature": "<solana_tx_sig>", "invoice_id": "inv_..."}'

# 4. Retry original call — wallet is now funded
GET /api/v1/wallet/deposit/status/:invoiceId Authenticated

Check the status of a payment invoice. Invoices are created when a toll call fails due to insufficient balance.

Response 200
{
  "invoice_id": "inv_e7e72df3a84a1406",
  "agent_id": "ext_my-agent",
  "amount_usd": 0.0001,
  "status": "pending",
  "description": "mcp:check_email_health",
  "solana_signature": null,
  "paid_at": null,
  "created_at": "2026-03-10T04:50:00.000Z"
}

Rates API

GET /api/v1/toll/rates Public

Current rate schedule for all metered operations.

Response 200
{
  "mcp_call": 0.0001,
  "email_forward": 0.0002,
  "rest_api": 0.00005,
  "agent_invoke": 0.0003
}
GET /api/v1/toll/estimate Authenticated

Calculate estimated cost before executing a batch of operations.

Query Parameters
GET /api/v1/toll/estimate?mcp_calls=100&forwards=50&api_calls=200&invocations=10
Response 200
{
  "estimate_usd": 0.033,
  "breakdown": {
    "mcp_calls": 100,
    "forwards": 50,
    "api_calls": 200,
    "invocations": 10
  },
  "rates": {
    "mcp_call": 0.0001,
    "email_forward": 0.0002,
    "rest_api": 0.00005,
    "agent_invoke": 0.0003
  }
}

MCP Integration

ARC-Relay exposes email tools via the Model Context Protocol (JSON-RPC 2.0). When you use an agent key, each tools/call automatically deducts $0.0001 from your wallet.

Claude Desktop / MCP Client Config

claude_desktop_config.json 
{
  "mcpServers": {
    "arc-relay": {
      "url": "https://arc-relay.com/mcp",
      "headers": {
        "Authorization": "Bearer ar_agent_my-agent_YOUR_KEY_HERE"
      }
    }
  }
}

Example: tools/call

Request 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "check_email_health",
    "arguments": { "domain": "example.com" }
  }
}
Response (200) 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "{ \"domain\": \"example.com\", \"score\": 100, ... }" }
    ]
  }
}

Available Methods

Method Description
initializeHandshake, returns server capabilities
tools/listList all available tools with schemas
tools/callExecute a tool (metered at $0.0001/call)

402 Payment Required

When your agent's wallet balance is too low for an operation, you'll get a payment_required error with an invoice. Deposit funds and retry.

MCP Response

MCP returns this inside a valid JSON-RPC response (HTTP 200) with isError: true:

JSON-RPC Error Response 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{
        \"error\": \"payment_required\",
        \"estimate_usd\": 0.0001,
        \"balance_usd\": 0.0001,
        \"invoice_id\": \"inv_e7e72df3a84a1406\",
        \"deposit\": \"POST /api/v1/wallet/deposit\"
      }"
    }],
    "isError": true
  }
}

REST API Response

Non-MCP endpoints return an actual HTTP 402 status:

HTTP 402 
{
  "error": "payment_required",
  "estimate_usd": 0.00005,
  "shortfall_usd": 0.00004,
  "invoice_id": "inv_a1b2c3d4e5f67890",
  "payment_methods": [
    { "type": "api_deposit", "method": "POST /api/v1/wallet/deposit" }
  ]
}

Deposit & Retry Pattern

terminal 
# 1. MCP call fails — insufficient balance
# Response includes: "error": "payment_required", "invoice_id": "inv_..."

# 2. Deposit funds
curl -X POST https://arc-relay.com/api/v1/wallet/deposit \
  -H "Authorization: Bearer ar_agent_my-agent_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 1.00}'

# { "balance_usd": 1.0001 }

# 3. Retry the original MCP call — succeeds, $0.0001 deducted
curl -X POST https://arc-relay.com/mcp \
  -H "Authorization: Bearer ar_agent_my-agent_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_email_health","arguments":{"domain":"example.com"}}}'

Ready to build your first agent?

Register now and get $1.00 free — enough for 10,000 MCP calls.

curl -X POST https://arc-relay.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
Get Started Free