These routes take an agent wallet API key (
claw_ prefix) and bill USDC from the agent’s wallet. They reject Locus Pro keys (lcr_ or lcac_). For Locus Pro, see the Locus Pro API reference or the Locus Pro quickstart.How it works
Authentication
Create an agent wallet API key in the Locus dashboard. Your agent sends it as a Bearer token to quote, call a tool, or fetch a result. Catalog discovery is public and needs no key.Discover registered tools
GET https://api.paywithlocus.com/api/wrapped?provider=firecrawl returns one provider’s tools, with the exact provider/endpoint slugs. Leave out provider to list every tool.
Read a provider reference
Each provider has a generated reference page, such as firecrawl.md, listing every endpoint slug with its parameters, an example body, and the estimated price. The catalog links them all. Those pages show the Locus Pro form of each call, and call your agent wallet API key a Pay With Locus wallet key. To use your key, keep the endpoint slug and body, and change three things:
Providers marked Locus Pro only on a reference page have no wallet route and return
404.
Quote a call
Before spending, your agent sends the intended request to the tool’s/quote route. The quote checks the inputs and price without calling the provider.
Calls have a $0.001 minimum, and a provider’s free endpoint can still carry a Locus fee. Some endpoints, such as model chat, settle from the usage the provider reports. For those, the quote is the maximum charge, and the call’s X-Locus-Cost-Usd header shows the final amount.
Make a call
Your agent then sends the same body to the tool route, with two safety headers:Idempotency-Key: a unique ID for this call, reused on retries so a retry doesn’t run the call twice.X-Locus-Expected-Cost-Usd: the quoted price. If the price changed, Locus returns409 PRICE_CHANGEDbefore calling the provider.
Run a quoted request
data.
Approval flow
After you approve, your agent fetches the result from the returned result path with the same API key. It can also retry the identical request with the originalIdempotency-Key, which avoids a second call.
Enable and disable tools
In the dashboard, open Services → Agent tools. Locus-managed tools start enabled, and provider and tool toggles restrict access immediately.Error handling
401: check the API key.402: fund the wallet.403: check tool access, spending limits, or approval status.409: read the response for a price change or a call already in progress.
X-Locus-Retry-Safe: true, Locus never sent it to the provider. Without that header, the provider may have accepted the work, so retry only with the original idempotency key. Provider-specific errors are in each provider reference.
Next steps
Tool catalog
Find a provider and its reference.
Spending controls
Set the threshold that triggers approvals.