FROM API KEY TOLIVE METER.

QUICK START / 01

FROM ACCOUNT
TO FIRST SESSION.

Create an approved merchant account, register one product, then open a session after the customer has a funded balance.

1. Open /merchant/apply
2. Submit product and rail requirements
3. Verify the same email at /merchant/login
4. Wait for merchant status = approved

curl -X POST "$METR_API/api/v1/merchant/products" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "name": "GPU access",
    "chain": "base",
    "rateUnit": "minute",
    "pricePerUnit": "0.10",
    "graceSeconds": 30,
    "maxSpendPerSession": "5.00"
  }'

curl -X POST "$METR_API/api/v1/customer/sessions/start" \
  -H "authorization: Bearer $CUSTOMER_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "productId": "prod_abc123" }'

AUTHENTICATION / 02

IDENTITY BEFORE
VALUE MOVES.

Merchant sign-in uses a short-lived Privy access token. The Metr server verifies that token and independently checks the linked application’s approval status. Programmatic product access uses scoped merchant API keys, which should remain outside client code.

authorization: Bearer PRIVY_ACCESS_TOKEN

CORE CONCEPTS / 03

ONE OBJECT CONNECTS
THE LIFECYCLE.

A product defines the commercial rule. A funded balance authorizes spend. A session connects the customer, rate, active time, total charge, and final record.

Product fields

Session lifecycle

CUSTOM TOKENS / 04

CONFIGURE THE RAIL.
VERIFY THE ASSET.

The legacy contract included merchant-registered SPL and ERC-20 rails. The safe operational model is register → validate contract and decimals → verify pricing/liquidity assumptions → enable per product.

POST /api/v1/merchant/tokens
{
  "chain": "base",
  "tokenAddress": "0x…",
  "symbol": "TOKEN",
  "name": "Example Token",
  "decimals": 18
}

API REFERENCE / 05

THE COMPLETE
ROUTE MAP.

All legacy routes were grouped under /api/v1. Requests and responses use JSON unless a specific integration says otherwise.

{
  "id": "session_uuid",
  "status": "active",
  "startedAt": "2026-08-27T18:00:00.000Z",
  "totalSeconds": 0,
  "totalCharged": "0"
}

BILLING LOGIC / 06

VISIBLE RULES.
DETERMINISTIC MATH.

The legacy billing model tracked elapsed time, applied any configured grace period, rounded billable time to engine intervals, then enforced the remaining session cap before recording a charge.

rate = $0.10 / minute
elapsed = 45 seconds
grace = 30 seconds
billable = 15 seconds
charge = billable × rate_per_second

CHAINS & ASSETS / 07

PRODUCT-SCOPED
SETTLEMENT.

The prior docs modeled products on Solana, Polygon, Base, and Robinhood Chain, with stablecoin, native, or configured custom-token paths. Treat this as architecture scope; enabled production rails are confirmed per account.

MCP SERVER / 08

LET AGENTS DISCOVER
THE BILLING SURFACE.

The legacy MCP design exposed public discovery tools and authenticated session tools over streamable HTTP. The same deposit and session policies apply; the MCP layer does not bypass verification.

{
  "mcpServers": {
    "metr": {
      "url": "$METR_API/api/v1/mcp",
      "headers": { "x-api-key": "metr_your_key" }
    }
  }
}

ERROR HANDLING / 09

FAIL CLEARLY.
STOP SAFELY.

{
  "message": "insufficient balance for this product"
}