Core concepts

MeterCall is built around seven primitives. Once you know these, the whole API fits in your head.

Module #

A module is a packaged capability exposed at /v1/module/:slug/call. It can wrap a third-party API (Stripe, Twilio, Notion), a hosted AI model, or original logic written by a builder. Every module has a slug, a price schedule (per-call, per-token, per-MB), a JSON action schema, and an owner who earns revenue share on every call.

Diagram: a module is a box with an action input port on the left and a result output port on the right. A meter sits between the two, counting every invocation and routing a sliver of revenue to the owner.

{
  "slug": "stripe-replacement",
  "price": {"unit": "call", "cents": 3},
  "owner": "agent_01HY...",
  "actions": ["charge", "refund", "payout"]
}

Agent #

An agent is a non-human identity with its own key, wallet, and reputation. Agents sign in with a nonce-challenge (/api/agent/nonce then /api/agent/signin) and from that point they can call modules, publish modules, and pay other agents.

Diagram: imagine a robot holding a keychain. One key opens your account, another holds USDC, a third signs HTTP headers. That's an agent.

Wallet #

A wallet is where value lives. Every account and every agent has one. Wallets hold three kinds of balance:

• Credits — prepaid in USD, consumed as you make calls.
• USDC — on-chain balance connected via /api/wallet/connect; used by x402 agent-pay.
• Card — fallback method billed monthly for overage.

Diagram: three parallel tanks feeding a single outflow meter. When a call costs $0.03, the meter drains whichever tank you've pointed at.

Call #

A call is one invocation of a module. Each call has: a unique call_id, a caller (your key or an agent), a target module, an action, a cost in cents, a latency, a status, and — on success — a result payload. Calls are the billable unit.

Diagram: a straight line from caller → meter → module → back. Every arrow is stamped with the call_id.

Credit #

A credit is a prepaid cent. Fund your wallet at /api/wallet/fund and credits land immediately. Credits never expire for paying accounts. Promo credits (from referrals or launch coupons) expire 90 days after grant.

Diagram: a stack of coins labeled with the grant date. The meter pulls from the oldest stack first (FIFO).

Receipt #

A receipt is the tamper-proof record of a call. MeterCall returns one with every billable response:

{
  "call_id": "call_01HY...",
  "module": "stripe-replacement",
  "cost_cents": 3,
  "timestamp": "2026-04-16T19:12:11Z",
  "hash": "sha256:9c2f..."
}

Concatenate the JSON in canonical form (sorted keys, no whitespace), hash with SHA-256, and verify with Ed25519 using the public key at /.well-known/metercall-pubkey.

Diagram: a paper receipt with a wax seal. Break the seal and the numbers won't match.

Signature #

A signature proves authorship. Three places use them:

• Agent signin. The agent signs a server-issued nonce with their private key to get a session token.
• X-Payment headers. x402 payment blobs are signed so the receiver can verify the payer and amount off-chain.
• Receipts. Every billable response carries an X-Receipt-Sig produced by MeterCall's signing key.

Diagram: a sealed envelope with a visible wax seal on the flap. The seal ID is public, so anyone with the ring can verify — no one but the holder can forge.