Quickstart

From zero to a billable, metered API call in five minutes. You will get a key, make a request, handle the 402 Payment Required path, check usage, and wire up a spend alert.

1. Get an API key #

You can create keys from the dashboard or directly via the API. The response returns the key once — store it securely.

curl -X POST https://metercall.ai/api/keys \
  -H "Authorization: Bearer mc_sess_YOURSESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"local-dev","scopes":["call:read","call:write"]}'

Response

{
  "id": "key_01HY...",
  "name": "local-dev",
  "key": "mc_live_abc123xyz...",
  "scopes": ["call:read", "call:write"],
  "created_at": "2026-04-16T18:00:00Z"
}

2. Make your first call #

Every module is reachable at /v1/module/:slug/call. The body is the module's own action schema — we pass it straight through.

curl -X POST https://metercall.ai/v1/module/stripe-replacement/call \
  -H "Authorization: Bearer mc_live_abc123xyz..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_7f3e..." \
  -d '{
    "action": "charge",
    "amount": 4900,
    "currency": "usd",
    "source": "tok_visa"
  }'

Response (200)

{
  "ok": true,
  "module": "stripe-replacement",
  "call_id": "call_01HY...",
  "cost_cents": 3,
  "result": {
    "charge_id": "ch_3P...",
    "status": "succeeded"
  },
  "receipt": {
    "hash": "sha256:...",
    "sig": "ed25519:..."
  }
}

3. Handle 402 Payment Required #

If your key has no balance or the caller is an unauthenticated agent, MeterCall returns 402 with instructions for how to pay inline.

HTTP/1.1 402 Payment Required
WWW-Authenticate: X-Payment realm="metercall"
X-Price-Cents: 3
X-Accepted-Methods: credits,usdc,card

{
  "error": "payment_required",
  "price_cents": 3,
  "pay_to": "0xMeterCall...",
  "nonce": "n_01HY..."
}

Retry the request with an X-Payment header containing a signed payment blob. For agent wallets, the SDK handles this automatically — see Agent-pay (x402).

curl -X POST https://metercall.ai/v1/module/stripe-replacement/call \
  -H "Authorization: Bearer mc_live_..." \
  -H "X-Payment: eyJ2ZXIiOiJ4NDAyLjEiLCJuIjoibl8..." \
  -H "Content-Type: application/json" \
  -d '{"action":"charge","amount":4900,"currency":"usd","source":"tok_visa"}'

4. Track usage #

Usage is available as a rolling window. Query /api/usage/current for this billing period, or /api/usage/by-module for a breakdown.

curl https://metercall.ai/api/usage/current \
  -H "Authorization: Bearer mc_live_..."

Response

{
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "calls": 1287,
  "spend_cents": 3861,
  "plan_cents": 14900
}

5. Set an alert #

Alerts watch any usage metric and fire a webhook (or email) when the condition is met. Common: cap monthly spend.

curl -X POST https://metercall.ai/api/alerts \
  -H "Authorization: Bearer mc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly spend > $100",
    "metric": "spend_cents",
    "op": ">",
    "threshold": 10000,
    "window": "month",
    "channel": "email",
    "target": "ops@acme.co"
  }'

Response

{
  "id": "alt_01HY...",
  "state": "armed",
  "last_fired": null
}

You're live. Now what? #

• Read Core concepts to understand modules, wallets, and receipts.
• Pick an SDK from SDKs to stop writing curl.
• If you're building an AI agent, jump to Agent-pay (x402).
• Browse Examples for common integrations.