Documentation

API Documentation

Use Rhumb for discovery, capability routing, pricing, and execution. Discovery reads are open. Execution supports governed API keys, wallet-prefunded API keys, BYOK credential passthrough, or X-Payment for x402 per-call auth.

Base URL: https://api.rhumb.dev/v1

Best current fit

Use Rhumb first for research, extraction, generation, and narrow enrichment. That is the cleanest launchable surface today.

Current boundary

Do not read the current docs as a promise of general business-agent automation. Treat broad orchestration as future scope, and Layer 3 as beta with a sparse public catalog.

Start here

Resolve mental model in 60 seconds

Default path: discover a Service, choose a Capability, estimate the call, then execute through Layer 2 with a governed API key or wallet-prefunded API key. Use x402 only when zero-signup per-call matters. Use Layer 1 only when you must pin the provider. Use Layer 3 only when a published recipe already exists.

Interface surfaces

REST API

Use direct HTTP when you want explicit endpoint, header, and response control.

MCP

Use tools when your agent already speaks MCP and should call Rhumb as a tool provider.

Entity types

Service

A vendor or product Rhumb evaluates, ranks, and compares.

Capability

An executable action like email.send or search.query that can map to multiple Services.

Recipe (beta)

A deterministic multi-step workflow compiled on top of Capabilities. Public catalog may still be sparse.

Execution layers

Layer 1

Raw provider access. You pin the provider yourself.

Layer 2

Capability routing. Rhumb picks the best provider and is the main production surface today.

Layer 3

Deterministic recipes. Real but still beta, with intentionally sparse public inventory.

Auth + payment rails

Discovery

Free, open read path for search, scores, failures, leaderboards, and capability browsing.

Governed API key

Account-first execution with managed billing, routing, and dashboard controls.

Wallet-prefund

Wallet authenticates once, tops up reusable balance, then executes repeat traffic via X-Rhumb-Key.

x402 per-call

Zero-signup per-call USDC payment. Best when autonomous pay-as-you-go matters more than repeat throughput.

Credential modes

BYO

You bring the upstream credential; Rhumb routes the call.

Rhumb-managed

Rhumb holds the provider credential so the agent can start faster.

Agent Vault

Your credential stays encrypted in agent-controlled storage and is injected at execution time.

Auth + payment rails

Discovery

Read endpoints like scores, search, capabilities, and leaderboards are open.

Governed API key

Use X-Rhumb-Key for account-first execution with dashboard-backed billing controls.

Wallet-prefund

Wallet signs once, tops up reusable balance, then executes repeat traffic with X-Rhumb-Key.

x402 per-call

Use X-Payment for zero-signup, per-call USDC payment on Base. Current public execute compatibility is the legacy tx-hash proof flow; standard authorization payloads belong on the wallet-prefund top-up rail.

Wallet-prefund flow (API-first)

This is the bridge between wallet-first identity and reusable execution balance. Top-ups settle through x402, then execution runs through the normal X-Rhumb-Key path.

POST /v1/auth/wallet/request-challenge
POST /v1/auth/wallet/verify
GET  /v1/auth/wallet/me
POST /v1/billing/x402/topup/request
POST /v1/billing/x402/topup/verify
POST /v1/capabilities/{capability_id}/execute   # with X-Rhumb-Key

REST API

GET /v1/services/{slug}/score

Full AN Score breakdown for a service.

Request

curl https://api.rhumb.dev/v1/services/stripe/score

Response

{
  "data": {
    "slug": "stripe",
    "an_score": 8.1,
    "tier": "L4 Native",
    "execution_score": 8.4,
    "access_readiness_score": 7.3,
    "failure_count": 2,
    "review_count": 47
  },
  "error": null
}

GET /v1/search?q={query}

Search services by need, category, or description.

Request

curl "https://api.rhumb.dev/v1/search?q=send+email"

Response

{
  "data": {
    "query": "send email",
    "results": [
      {
        "service_slug": "google-workspace-apis",
        "name": "Google Workspace APIs",
        "aggregate_recommendation_score": 8.7,
        "tier": "L4"
      }
    ]
  },
  "error": null
}

GET /v1/capabilities/{capability_id}

Inspect a capability and the providers that can fulfill it.

Request

curl https://api.rhumb.dev/v1/capabilities/email.send

Response

{
  "data": {
    "id": "email.send",
    "provider_count": 8,
    "providers": [
      {
        "service_slug": "resend",
        "credential_modes": ["byo", "rhumb_managed"],
        "cost_per_call": 0.001
      }
    ]
  },
  "error": null
}

GET /v1/capabilities/{capability_id}/resolve

Resolve a capability to ranked providers, with routing hints and fallback chain.

Request

curl https://api.rhumb.dev/v1/capabilities/email.send/resolve

Response

{
  "data": {
    "capability": "email.send",
    "providers": [
      {
        "service_slug": "resend",
        "recommendation": "preferred",
        "cost_per_call": 0.001,
        "credential_modes": ["byo", "rhumb_managed"]
      }
    ],
    "fallback_chain": ["resend", "sendgrid"]
  },
  "error": null
}

GET /v1/capabilities/{capability_id}/execute/estimate

Estimate provider, cost, and circuit state before executing.

Request

curl https://api.rhumb.dev/v1/capabilities/email.send/execute/estimate

Response

{
  "data": {
    "capability_id": "email.send",
    "provider": "resend",
    "credential_mode": "auto",
    "cost_estimate_usd": 0.001,
    "circuit_state": "closed",
    "endpoint_pattern": "/emails"
  },
  "error": null
}

POST /v1/capabilities/{capability_id}/execute

Execute through Rhumb with governed API key, wallet-prefunded API key, BYOK / agent token, or x402 payment.

Request

curl -X POST "https://api.rhumb.dev/v1/capabilities/email.send/execute" \
  -H "X-Rhumb-Key: rhumb_live_..." \
  -H "Content-Type: application/json" \
  -d '{"body": {"to": "[email protected]", "subject": "Hello", "body": "Hi from Rhumb"}}'

Response

{
  "data": {
    "capability_id": "email.send",
    "provider": "resend",
    "upstream_status": 202,
    "credential_mode": "rhumb_managed"
  },
  "error": null
}

POST /v1/capabilities/{capability_id}/execute (x402)

Anonymous execution path. First request returns HTTP 402 with exact payment requirements.

Request

curl -X POST "https://api.rhumb.dev/v1/capabilities/email.send/execute" \
  -H "Content-Type: application/json" \
  -d '{"body": {"to": "[email protected]", "subject": "Hello"}}'

Response

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxAmountRequired": "10000"
    }
  ],
  "balanceRequiredUsd": 0.01
}

MCP Server

Rhumb provides an MCP server for discovery, routing, execution, billing, and telemetry. Current public server surface: 21 tools.

Install & run

RHUMB_API_BASE_URL="https://api.rhumb.dev/v1" npx rhumb-mcp@latest

Available tools

find_services

Search services by need.

find_services("payment processing")

get_score

Get the full AN Score breakdown for a service.

get_score("stripe")

get_alternatives

Find alternatives ranked by AN Score.

get_alternatives("paypal")

get_failure_modes

Inspect known breakage patterns before integrating.

get_failure_modes("stripe")

discover_capabilities

Browse capabilities like email.send or scrape.extract.

discover_capabilities({ search: "email" })

resolve_capability

Rank providers for a capability.

resolve_capability("email.send")

estimate_capability

Estimate cost and routing before execution.

estimate_capability("email.send")

execute_capability

Execute a capability through Rhumb Resolve.

execute_capability("email.send", { body: { to: "[email protected]" } })

credential_ceremony

Get self-service credential setup instructions.

credential_ceremony("github")

check_credentials

See which credential modes are available to you.

check_credentials("email.send")

budget

Check or set spend limits.

budget()

spend

Review spending by period, capability, and provider.

spend()

routing

Get or set routing preferences.

routing()

usage_telemetry

Inspect latency, errors, provider health, and usage trends.

usage_telemetry({ days: 7 })

check_balance

Check current Rhumb credit balance.

check_balance()

get_payment_url

Generate a top-up URL for prepaid credits.

get_payment_url({ amount_usd: 25 })

get_ledger

Review billing history.

get_ledger()

rhumb_list_recipes

Check the current published Layer 3 recipe catalog. Public inventory may be empty while Layer 3 remains in beta.

rhumb_list_recipes({ limit: 10 })

rhumb_get_recipe

Inspect a recipe definition only after confirming it appears in rhumb_list_recipes.

rhumb_get_recipe("published_recipe_id")

rhumb_recipe_execute

Execute a published Rhumb recipe once it is live in the public catalog.

rhumb_recipe_execute("published_recipe_id", { inputs: { email: "[email protected]" } })

get_receipt

Retrieve a chain-hashed execution receipt.

get_receipt("rcpt_123")

Notes

• Execution body shape — send nested JSON like {"body": {...}}, not flat top-level fields.
• Estimate first — use GET /v1/capabilities/{id}/execute/estimate before paid execution.
• x402 proof — retry direct execute with X-Payment carrying tx_hash, network, and wallet_address. If your wallet emits a standard x402 authorization payload instead, use the wallet-prefund top-up flow rather than the direct execute retry path.
• Layer 3 public state — the recipe tooling is live, but the public catalog can still be empty. Check /recipes or run rhumb_list_recipes before assuming a workflow exists.
• Canonical public pricing contract — see /pricing or GET /v1/pricing.

Quickstart → Agent Payments → Pricing → System Status →