# How it works

RouterGrowth is the OpenRouter for growth: one API that routes growth data calls (SEO, enrichment, company signals, social, ads) across curated providers. One key, one prepaid wallet, pay per call. No subscription, no seats.

## The loop

Every integration, human or agent, runs the same three-step loop:

1. **Discover.** `POST /v1/discover` with a plain-language job description ("find a verified email for a person") returns matching capabilities with status and starting price. Free, never executes a paid call.
2. **Inspect.** `POST /v1/inspect` returns a capability's input schema, output fields, the providers behind it, the exact versioned price and the billing conditions (for example: unmatched lookups are not billed).
3. **Run.** `POST /v1/run` executes it. The price you saw at inspect time is the price you pay; nothing bills without a reserved quote.

## Accounts, keys and the wallet

- An **organization** owns everything: keys, wallet, runs, connections.
- **API keys** come in two environments: `rg_test_` (sandbox) and `rg_live_` (production). Keys are hashed at rest and the raw key is shown exactly once, at creation. Mint and revoke via [`/v1/api-keys`](/docs/api/keys) or the [dashboard](/dashboard).
- The **wallet** holds prepaid USD credits, accounted in integer microdollars on an immutable ledger. Every reserve, settle, release, top-up and refund is a ledger entry you can read back via [`/v1/wallet/transactions`](/docs/api/wallet).

## Reserve, settle, release

A run never charges more than it quoted:

1. Before the provider call, the maximum billable amount is **reserved** against your balance. Insufficient funds fail fast with `insufficient_balance`, before any provider is touched.
2. On success the reservation **settles** to the actual charge (which can be lower, never higher).
3. On failure, timeout or an unbilled no-match, the reservation is **released** in full.

`routing.max_cost` adds your own cap on top: any offer above it is excluded before the call.

## Routing and waterfall failover

Set `routing.provider` to `auto` (default) and pick a strategy: `cheapest`, `fastest`, `highest_success_rate` or `best_value` (default). Or pin a specific provider by slug. Every response carries a `routing_reason` explaining the decision.

On auto routing, a provider error, timeout or unbilled no-match falls through to the next-best provider automatically, up to 3 attempts. Only the provider that delivers is charged, and every attempt is listed in the response's `attempts` array. Disable with `routing.allow_fallback: false`. A pinned provider never falls back.

## Sandbox and production

The sandbox (`rg_test_` keys) runs the full loop, quote, reserve, settle, with providers in mock mode returning clearly-labeled simulated data, so you can build the whole integration before spending a cent. Force outcomes for testing by including `nomatch`, `fail` or `timeout` in any input string.

In production, routing only considers providers with a live adapter: a paid call is never served simulated data, and capabilities without a live provider return `provider_not_available` until one is wired.

## Bring your own key

Already under contract with a provider? [Connect that provider's API key](/docs/api/connections) and calls to it route through your key instead of the platform's. BYOK calls are not metered by RouterGrowth.

## Where to next

- [Quickstart: API](/docs/quickstart-api), a first call in five minutes.
- [Quickstart: CLI](/docs/quickstart-cli), the same loop from the terminal.
- [Quickstart: agents](/docs/quickstart-agents), install the skill once, use it everywhere.
- [API reference](/docs/api/overview), every endpoint in detail.