/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: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: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:
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:
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.
200):
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 returns202 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.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 return403.
Error handling
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.