Skip to main content
This guide covers the legacy Agent Platform /api/wrapped surface. For Locus Pro credit-based tools and MCP, start with the Locus Pro quickstart.

Authentication

Executing a tool, quoting a call, or retrieving a stored call requires a Locus agent API key:
Catalog discovery at GET /api/wrapped is public. API keys are created in the Locus dashboard when you set up an agent; the key identifies the agent and wallet used for execution.

Discover registered tools

Fetch all registered tool slugs and metadata:
The response has this shape, abridged to one endpoint:
data.endpoints contains exact provider/endpoint execution slugs. Each data.catalog[] entry is { provider, display?, endpoints }; each endpoint is { slug, method, display? }. The displayed method describes the provider operation, while calls through Locus use POST. Filter to one registered provider with:
The filtered response keeps the same envelope. An unknown provider returns 404; an invalid provider query returns 400. Discovery lists registered tools, not only tools enabled for this agent; enablement is checked at execution time. For a compact Markdown contract containing exact request fields, examples, and current estimated prices, fetch the generated provider reference:

Quote a call

Send the intended body to the sibling /quote route. It validates and prices the request without calling the provider:
Read the authoritative total from data.price_usdc or X-Locus-Cost-Usd. Prices are rounded up to six USDC decimal places and have a $0.001 minimum. A zero upstream price can still carry a Locus fee.

Make a call

Use one idempotency key per logical call and preserve it for every same-route retry. X-Locus-Expected-Cost-Usd is optional; use it to reject execution if the resolved price changed after quoting.
Success response (200):
The data field contains the provider response. Preserve the Idempotency-Key and returned X-Locus-Cost-Usd for result retrieval and reconciliation.

Approval flow

A call above the agent’s approval threshold returns 202 Accepted. The response also sets Location to result_path:
1

Send the approval URL

Give approval_url to the human approver. Do not start a new unkeyed tool call.
2

Approval starts execution

After approval, Locus executes the stored request automatically. The caller still needs to collect its result.
3

Collect the result

GET https://api.paywithlocus.com${result_path} with the same Bearer key. Pending approval returns 202; active execution returns 409 with Retry-After: 2; denial returns 403; and a terminal call replays its stored success or error response.
If the original request used an Idempotency-Key, retrying the identical request with that same key is an alternative to polling result_path. Never retry it with a new key.

Policy guardrails

Your human can configure spending limits in the dashboard. These apply to all Agent Platform tool calls.

Enable and disable tools

Open Services → Agent tools in the dashboard. Locus-managed tools default to enabled. Provider- and tool-level toggles restrict execution; disabled tools return 403.

Error handling

Retry or reroute only when X-Locus-Retry-Safe: true guarantees that no provider request was dispatched. X-Locus-Upstream-Attempted: true means dispatch occurred; absence of both headers is not a retry-safety guarantee. For a same-route retry, reuse the original Idempotency-Key.
On provider failure, Locus records the error and attempts to restore the pre-call promo-credit or allowance deduction. Legacy Agent Platform tool responses are buffered; they do not use the Locus Pro streaming-capture rule.

Locus-managed tools vs x402 tools