How Rhumb works

Discover first. Execute what is ready.

Rhumb helps agents discover what services and capabilities exist across the web, compare them with public evidence, and execute supported actions through governed access rails. Discovery is broad. Governed execution is selective and explicit.

Start here Browse capabilities

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. Discovery is wider than current governed execution, and that honesty is part of the product.

Before you wire this deeper

Want to evaluate the trust story first? Read Trust, inspect the public Methodology, or use the provider dispute path if a score or claim looks wrong.

Route picker

Pick the right entrypoint before you read the whole manual

Cold start should not require inference. Evaluating with curl starts on the free discovery rail. Building an agent starts with MCP. Needing a reusable execution key starts with account setup. Services answer who to trust. Capabilities answer what Rhumb can execute.

Evaluator path

Evaluating with curl

Free reads

Start with the free read endpoints. See real responses, learn the product model, and judge the trust layer before signup.

Best when you are sizing up Rhumb, sharing a first link, or validating the discovery story with minimal setup.

Start here →

Builder path

Building an agent

MCP first

Install the MCP server or use the starter prompt. Reach for capability IDs when the agent needs executable actions, not just vendor names.

Best when Claude, Codex, Cursor, or another runtime already speaks tools and should keep Rhumb inside the loop.

Start here →

Operator path

Need an account and reusable key

Default rail

Sign up for identity, add credits, then execute with X-Rhumb-Key. Signup creates the account. Funding unlocks governed execution.

Best when you want managed routing, dashboard controls, spend visibility, and repeat traffic on one stable key.

Start here →

Start here

The Rhumb mental model in 60 seconds

Do not start with install details. Start with the route. Rhumb helps agents discover the landscape, decide with evidence, and execute only where a governed path is truly ready.

Discover first

Search 999 scored services and 435 mapped capabilities before you commit to a provider or rail.

Decide with evidence

Use scores, freshness, evidence tiers, and failure modes to explain the route instead of guessing.

Execute what is ready

Use Rhumb Resolve when a governed action is supported. Best current fit is research, extraction, generation, and narrow enrichment.

If execute blocks

A 402 is a handoff, not a dead end.

Discovery can keep moving even when execution is not ready. When execute returns an auth or payment handoff, follow the default rail first unless your runtime clearly supports a wallet path.

Governed API key

Default

Most buyers should start here. Sign in, fund the account, retry with X-Rhumb-Key.

Wallet-prefund

Wallet-first

Use this when wallet identity matters and the same agent will call repeatedly.

x402 per-call

Zero-signup

Use this only when request-level payment authorization is the requirement and the runtime can pay from a wallet.

Starter prompt

This is the cold-start path the homepage points agents to.

Use this when a human wants to hand Rhumb to Claude, Codex, or another agent without assuming prior workspace context or a preinstalled integration.

Use Rhumb as the first stop for this task.

Start here: https://rhumb.dev/docs#pick-your-route

1. Pick the right path first: MCP if you are wiring an agent, quickstart curl if you are evaluating, account setup if you need governed execution with X-Rhumb-Key.
2. Use service search when you are choosing vendors. Use capability search when you need the exact executable action slug.
3. Compare the top options using scores, evidence, freshness, and failure modes.
4. If Rhumb supports a governed action, estimate the active rail and execute it through Resolve.
5. If execution is not supported or credentials are missing, stay on the public discovery flow and tell me the best next step.

Task: [replace with your task]

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 or tool path yourself.

Layer 2

Capability routing. Rhumb routes each call to a supported provider using the capability candidate set, runtime factors, and explicit constraints; this 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 paths

BYOK

You bring the upstream credential; Rhumb routes the call without taking custody of your system credential.

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.

Quick reference

Once you have the route, these are the live public surfaces and the base URL behind the examples below.

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

Services scored

999

Capabilities mapped

435

Providers callable

Live surfaces

API + MCP

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?search={query}

Search executable action IDs when you know the job but not the capability slug.

Request

curl "https://api.rhumb.dev/v1/capabilities?search=web+research"

Response

{
  "data": {
    "items": [
      {
        "id": "search.query",
        "description": "Search the web through a provider-backed execution rail",
        "provider_count": 6,
        "top_provider": {
          "slug": "brave-search",
          "tier_label": "L4 Native"
        }
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  },
  "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": ["byok", "rhumb_managed"],
        "cost_per_call": 0.001
      }
    ]
  },
  "error": null
}

GET /v1/capabilities/{capability_id}/resolve

Resolve a capability into ranked providers, execute hints, machine-readable recovery fields when the requested rail is not ready, and search suggestions when the capability ID is wrong.

Request

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

Response

Common success response
{
  "data": {
    "capability": "email.send",
    "providers": [
      {
        "service_slug": "resend",
        "recommendation": "preferred",
        "cost_per_call": 0.001,
        "credential_modes": ["byok"]
      }
    ],
    "fallback_chain": ["resend", "sendgrid"],
    "related_bundles": [],
    "execute_hint": {
      "preferred_provider": "resend",
      "selection_reason": "highest_ranked_provider",
      "endpoint_pattern": "POST /emails",
      "estimated_cost_usd": 0.001,
      "auth_method": "api_key",
      "configured": false,
      "credential_modes": ["byok"],
      "credential_modes_url": "/v1/capabilities/email.send/credential-modes",
      "preferred_credential_mode": "byok",
      "fallback_providers": ["sendgrid"],
      "setup_hint": "Set RHUMB_CREDENTIAL_RESEND_API_KEY environment variable or configure via proxy credentials"
    }
  },
  "error": null
}

Representative recovery response when ranked providers exist but none are execute-ready on the requested rail
{
  "data": {
    "capability": "email.send",
    "providers": [
      {
        "service_slug": "resend",
        "recommendation": "preferred",
        "credential_modes": ["byok"]
      },
      {
        "service_slug": "sendgrid",
        "recommendation": "available",
        "credential_modes": ["byok"]
      }
    ],
    "fallback_chain": [],
    "related_bundles": [],
    "execute_hint": null,
    "recovery_hint": {
      "reason": "no_execute_ready_providers",
      "resolve_url": "/v1/capabilities/email.send/resolve",
      "credential_modes_url": "/v1/capabilities/email.send/credential-modes",
      "supported_provider_slugs": ["resend", "sendgrid"],
      "supported_credential_modes": ["byok"],
      "setup_handoff": {
        "preferred_provider": "resend",
        "auth_method": "api_key",
        "configured": false,
        "credential_modes": ["byok"],
        "credential_modes_url": "/v1/capabilities/email.send/credential-modes",
        "preferred_credential_mode": "byok",
        "selection_reason": "highest_ranked_provider",
        "setup_hint": "Set RHUMB_CREDENTIAL_RESEND_API_KEY environment variable or configure via proxy credentials"
      }
    }
  },
  "error": null
}

Other recovery cases reuse the same recovery_hint shape with a different reason.

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

Estimate the active execution rail, cost, and health before execution. Anonymous direct system-of-record rails also include data.execute_readiness so the next API-key step stays machine-readable.

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": "POST /emails"
  },
  "error": null
}

POST /v1/capabilities/{capability_id}/execute

Execute through Rhumb with the live execution rail returned by resolve: governed API key, wallet-prefund, or x402 per-call where supported. Some providers also support provider-controlled paths through BYOK or Agent Vault.

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": "user@example.com", "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": "user@example.com", "subject": "Hello"}}'

Response

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "payTo": "0x...",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxAmountRequired": "10000"
    }
  ],
  "resolution": "Default next step: create or use a funded governed API key at /auth/login and retry with X-Rhumb-Key.",
  "auth_handoff": {
    "recommended_path": "governed_api_key",
    "docs_url": "/docs#resolve-mental-model",
    "paths": [
      { "kind": "governed_api_key", "setup_url": "/auth/login", "retry_header": "X-Rhumb-Key" },
      { "kind": "wallet_prefund", "setup_url": "/payments/agent", "retry_header": "X-Rhumb-Key" },
      { "kind": "x402_per_call", "setup_url": "/payments/agent", "retry_header": "X-Payment" }
    ]
  }
}

MCP Server

Rhumb provides an MCP server for discovery, capability routing, supported execution, and account operations. 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({ query: "payment processing" })

get_score

Get the full AN Score breakdown for a service.

get_score({ slug: "stripe" })

get_alternatives

Find alternatives ranked by AN Score.

get_alternatives({ slug: "paypal" })

get_failure_modes

Inspect known breakage patterns before integrating.

get_failure_modes({ slug: "stripe" })

discover_capabilities

Browse capabilities like email.send or scrape.extract.

discover_capabilities({ search: "email" })

resolve_capability

Rank providers, filter by credential mode, surface machine-readable recovery fields like recovery_hint.resolve_url, recovery_hint.credential_modes_url, and, when applicable, recovery_hint.alternate_execute_hint or recovery_hint.setup_handoff, and recover typoed capability IDs with search suggestions.

resolve_capability({ capability: "email.send", credential_mode: "byok" })

estimate_capability

Estimate the active execution rail, cost, and health before execution. Anonymous direct system-of-record paths also preserve machine-readable execute_readiness handoffs.

estimate_capability({ capability_id: "email.send", credential_mode: "rhumb_managed" })

execute_capability

Execute a capability through Rhumb Resolve.

execute_capability({ capability_id: "email.send", credential_mode: "rhumb_managed", body: { to: "user@example.com" } })

credential_ceremony

Get self-service credential setup instructions.

credential_ceremony({ service: "github" })

check_credentials

Inspect live credential-mode readiness, globally or for a specific Capability.

check_credentials({ capability: "email.send" })

budget

Check or set spend limits.

budget({ action: "get" })

spend

Review spending by period, capability, and provider.

spend({ period: "30d" })

routing

Get or set routing preferences.

routing({ action: "get" })

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({ limit: 20 })

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({ recipe_id: "published_recipe_id" })

rhumb_recipe_execute

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

rhumb_recipe_execute({ recipe_id: "published_recipe_id", inputs: { email: "sam@acme.com" } })

get_receipt

Retrieve a chain-hashed execution receipt.

get_receipt({ receipt_id: "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 →