Skip to main content
Send your agent wallet/skill.md and it can pay for agent tools from its Locus agent wallet in USDC. It finds a tool, quotes the request, then calls it.
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 returns 409 PRICE_CHANGED before calling the provider.
Run a quoted request
Replace the example price with your quote. A successful response holds the provider result in 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 original Idempotency-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.
If a failed call has 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.