# Agent Platform
Source: https://docs.paywithlocus.com/agent-platform
Give your agent a wallet to pay for tools, deploy apps, and make purchases.
Give your agent a USDC wallet and a budget. It can pay for data, deploy an app, hire a tasker, or make an online purchase. You control how much it can spend and which payments need your approval.
Locus brings those payments into one balance and one transaction history. Gas is sponsored for Locus wallet transactions on Base.
## What your agent can do
| Task | How Locus helps |
| ---------------------------------- | -------------------------------------------------------------------------------- |
| Research a market or enrich a lead | Buy search, company data, and other [agent tools](/wrapped-apis/index) per call. |
| Turn a prototype into a live app | [Deploy services](/build/index), add a database, and connect a domain. |
| Sell a product or service | [Accept USDC payments](/checkout/index) from people and agents. |
| Pay a contractor | [Send USDC](/features/send-types) to a wallet address or email. |
| Buy something online | Order a [prepaid virtual Visa card](/features/laso) for the purchase. |
| Get human help | [Hire a tasker](/features/tasks) for design, writing, and other work. |
## Stay in control
Set a total allowance, a maximum transaction size, and an approval threshold in the dashboard. Review payments and the agent's reasoning in your transaction history.
Your [wallet](/features/wallets) has a user-owned recovery key. You can revoke Locus's permissioned signing key at any time.
## Get started
Send your agent the skill file, then follow the [quickstart](/quickstart) to create and fund its wallet:
```text theme={null}
Read https://paywithlocus.com/skill.md and help me set up an Agent Platform wallet.
```
You can test with a sandbox key before spending funds, or [request promotional credits](/promo-credits).
Connect your agent and make your first call.
Manage spending, tools, deployments, and payments.
# Begin or complete verified agent-owned signup
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/begin-or-complete-verified-agent-owned-signup
/api-reference/openapi.json post /credits/agent/register
A first request creates only a 30-minute pending row and returns an AgentID authorization URL. After AgentID PKCE verification, replaying the same name and registrationToken creates or recovers one zero-balance personal account and returns its scoped connection credential. The verified provider/subject pair is the durable one-account boundary. No free or bonus credits are issued.
# Complete AgentID authorization-code verification
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/complete-agentid-authorization-code-verification
/api-reference/openapi.json get /credits/agent/identity/agentid/callback
Exchanges an AgentID authorization code with PKCE, verifies ES256 issuer, audience, nonce, stable subject, and live inbox, and marks the pending signup identity-verified. The callback never returns a Locus credential; the agent replays POST /credits/agent/register to receive it.
# Create a human funding handoff
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/create-a-human-funding-handoff
/api-reference/openapi.json post /credits/agent/funding-sessions
Creates an exact-amount, one-hour Stripe Checkout Session for the authenticated agent account. The payer card is not attached to the agent account for future use. Reuse the Idempotency-Key for retries of the same logical link.
# Enable or disable one agent-owned capability
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/enable-or-disable-one-agent-owned-capability
/api-reference/openapi.json put /credits/agent/catalog
Changes only the enabled flag for one exact catalog slug on the self-registered account. It cannot change pricing or any other tenant setting.
# Get independently versioned platform compatibility
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/get-independently-versioned-platform-compatibility
/api-reference/openapi.json get /agent/compatibility.json
# Get the immutable public Locus guide release manifest
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/get-the-immutable-public-locus-guide-release-manifest
/api-reference/openapi.json get /agent/guides/manifest.json
# Poll an agent funding handoff
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/poll-an-agent-funding-handoff
/api-reference/openapi.json get /credits/agent/funding-sessions/{sessionId}
Returns ready only after the signed Stripe webhook has been durably consumed and the credit ledger balance is usable.
# Read agent funding constraints
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-agent-funding-constraints
/api-reference/openapi.json get /credits/agent/funding/config
Returns exact top-up limits and confirms that Checkout is Stripe-hosted, the payer does not become owner, and no reusable payment method is delegated to the agent.
# Read one public guide resource as a JSON envelope
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-one-public-guide-resource-as-a-json-envelope
/api-reference/openapi.json get /agent/guides/{bundleVersion}/{guideId}.json
# Read one public guide resource as Markdown or text
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-one-public-guide-resource-as-markdown-or-text
/api-reference/openapi.json get /agent/guides/{bundleVersion}/{guideId}.md
# Read one public guide resource using its declared media type
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-one-public-guide-resource-using-its-declared-media-type
/api-reference/openapi.json get /agent/guides/{bundleVersion}/{guideId}/content
# Read the agent-native onboarding contract
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-agent-native-onboarding-contract
/api-reference/openapi.json get /credits/agent/onboarding
Public machine-readable flow for a headless agent. No existing Locus tenant is required. AgentID verification creates identity friction before any durable account exists; the human is needed only for an optional AgentMail OTP and the later Stripe funding handoff.
# Read the agent-owned account
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-agent-owned-account
/api-reference/openapi.json get /credits/agent/account
Returns only the authenticated self-registered account, its usable pooled balance, expiry, links, and next action. Tenant-managed agent connections are rejected.
# Read the Locus AgentID client descriptor
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-locus-agentid-client-descriptor
/api-reference/openapi.json get /credits/agent/identity/agentid
# Read the payer-safe funding result
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-payer-safe-funding-result
/api-reference/openapi.json get /credits/agent/funding-sessions/public/{sessionId}
Public status used by the Stripe return page. The opaque Checkout Session ID is the capability. The response contains only state, agent display name, and credited amount; it never returns payer details or agent credentials.
# Rotate the agent-owned credential
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/rotate-the-agent-owned-credential
/api-reference/openapi.json post /credits/agent/credential/rotate
Atomically replaces the account recovery digest and bearer credential from a newly generated 24-byte base64url token, then extends expiry by 365 days.
# Search capabilities for an agent-owned account
Source: https://docs.paywithlocus.com/api-reference/agent-native-onboarding/search-capabilities-for-an-agent-owned-account
/api-reference/openapi.json post /credits/agent/catalog/search
Searches the mutable catalog, including disabled capabilities, so a dashboardless agent can find exact provider/endpoint slugs before enabling them. System-managed virtual router endpoints are omitted because ordinary catalog controls cannot toggle them.
# Create a scoped Agent Connection
Source: https://docs.paywithlocus.com/api-reference/authentication/create-a-scoped-agent-connection
/api-reference/openapi.json post /credits/agent-connections
Creates a short-lived, least-privilege lcac_ credential for MCP and wrapped execution. Because the returned credential can spend credits, callers must hold both credentials:manage and credits:move rather than delegating spend authority they do not hold. A secret key with both scopes may automate this route; human callers must be a workspace owner or admin with fresh MFA/passkey step-up.
# Inspect the current management credential
Source: https://docs.paywithlocus.com/api-reference/authentication/inspect-the-current-management-credential
/api-reference/openapi.json get /credits/auth/credential
Returns only the authenticated credential kind, tenant, role, effective scopes, and current step-up state. Owner and admin dashboard sessions are step-up eligible; developer, billing, viewer, and secret-key principals are not. It never returns raw keys, hashes, JWT claims, or secrets. Call this before attempting a scoped management operation.
# List scoped Agent Connections
Source: https://docs.paywithlocus.com/api-reference/authentication/list-scoped-agent-connections
/api-reference/openapi.json get /credits/agent-connections
Results are bounded to 100 records and sorted newest first. Follow nextCursor until null.
# Read one scoped Agent Connection
Source: https://docs.paywithlocus.com/api-reference/authentication/read-one-scoped-agent-connection
/api-reference/openapi.json get /credits/agent-connections/{connectionId}
# Resend a signup verification code
Source: https://docs.paywithlocus.com/api-reference/authentication/resend-a-signup-verification-code
/api-reference/openapi.json post /credits/auth/signup/resend
Always returns the same success shape for a syntactically valid email, whether or not an unconfirmed identity exists.
# Revoke a scoped Agent Connection credential
Source: https://docs.paywithlocus.com/api-reference/authentication/revoke-a-scoped-agent-connection-credential
/api-reference/openapi.json post /credits/agent-connections/{connectionId}/revoke
Idempotently revokes the lcac_ credential. A scoped secret key may automate this Agent Connection operation; human callers require owner/admin step-up.
# Rotate a scoped Agent Connection credential
Source: https://docs.paywithlocus.com/api-reference/authentication/rotate-a-scoped-agent-connection-credential
/api-reference/openapi.json post /credits/agent-connections/{connectionId}/rotate
Immediately invalidates the prior lcac_ credential and returns its spend-capable replacement once. Callers require credentials:manage and credits:move; a scoped secret key with both may automate this operation, while human callers additionally require owner/admin step-up.
# Start a self-serve Locus Pro account
Source: https://docs.paywithlocus.com/api-reference/authentication/start-a-self-serve-locus-pro-account
/api-reference/openapi.json post /credits/auth/signup
Creates an unconfirmed Cognito identity and sends a 6-digit email code. It does not provision a workspace or grant credits. Passwords require 8–256 characters with uppercase, lowercase, and numeric characters.
# Verify email and create the self-serve workspace
Source: https://docs.paywithlocus.com/api-reference/authentication/verify-email-and-create-the-self-serve-workspace
/api-reference/openapi.json post /credits/auth/signup/confirm
Confirms the email, proves knowledge of the chosen password, and atomically provisions one owner workspace tied to the Cognito subject. Replays return that same workspace. The workspace starts with exactly $0 and receives no free or promotional credits.
# Metered pay-per-use call
Source: https://docs.paywithlocus.com/api-reference/burn/metered-pay-per-use-call
/api-reference/openapi.json post /wrapped/credits/{provider}/{endpoint}
The response body is the RAW upstream response (byte-compatible with the provider SDK shape). Cost rides in response headers. `X-Locus-End-User` present (or an end-user token or end-user-bound Agent Connection) charges that user's account at your effective price; a secret-key call without it or a platform-mode Agent Connection charges your platform account at base price with zero markup.
# OpenAI-compatible metered chat completions
Source: https://docs.paywithlocus.com/api-reference/burn/openai-compatible-metered-chat-completions
/api-reference/openapi.json post /wrapped/credits/v1/chat/completions
Accepts the OpenAI Chat Completions request shape. With stream=true, returns provider-native SSE without full-response buffering. Locus captures the fixed authorized charge before delivering the first byte.
# Per-tenant generated docs (markdown)
Source: https://docs.paywithlocus.com/api-reference/burn/per-tenant-generated-docs-markdown
/api-reference/openapi.json get /credits/md
Enterprise workspace documentation for enabled endpoints and effective tenant pricing. Requires a management credential with tenant:read; personal accounts and end-user JWTs cannot use this route.
# Read async job result
Source: https://docs.paywithlocus.com/api-reference/burn/read-async-job-result
/api-reference/openapi.json post /wrapped/credits/calls/{callId}/result
Read the provider result of an async job, such as clado/bulk-contacts. Pass the apiCallId returned by the submit call. Locus reads the job id from that call's receipt. Reads are free and never create a new charge, so polling the same call again is safe. Access follows the submit endpoint's scope. Set waitSeconds to wait on the server for up to 45 seconds. When state is pending, call again after pollAfterMs. When nextPage is present, call again with its skip and limit to read the next page.
# Read authoritative stream state and final billing
Source: https://docs.paywithlocus.com/api-reference/burn/read-authoritative-stream-state-and-final-billing
/api-reference/openapi.json get /wrapped/credits/calls/{callId}
# Approve or deny tool access
Source: https://docs.paywithlocus.com/api-reference/catalog/approve-or-deny-tool-access
/api-reference/openapi.json post /credits/tool-access-requests/decision
Requires a signed-in member of the requested workspace with catalog:write. Approval enables the tool for that workspace; denial leaves its current setting unchanged.
# Clear a catalog override
Source: https://docs.paywithlocus.com/api-reference/catalog/clear-a-catalog-override
/api-reference/openapi.json delete /credits/catalog/{slug}
Removes a provider or endpoint override so pricing falls back to the next level up, ending at the workspace default. slug is provider (whole provider) or provider/endpoint (URL-encoded), the same forms PUT accepts. Idempotent: clearing something that has no override succeeds and reports cleared: false. This clears configuration only — it never disables an endpoint.
# Describe one selected tool
Source: https://docs.paywithlocus.com/api-reference/catalog/describe-one-selected-tool
/api-reference/openapi.json post /credits/tools/describe
Returns the full input schema, example, response contract, pricing, and next action for one principal-visible search result. Secret keys require tenant:read. This operation does not call a provider or burn credits.
# Enable or disable a bounded provider batch
Source: https://docs.paywithlocus.com/api-reference/catalog/enable-or-disable-a-bounded-provider-batch
/api-reference/openapi.json put /credits/catalog/bulk
Creates or updates up to 50 provider-level enablement rows in one transaction, and resets those providers' endpoint-level enablement overrides to inherit so the value you send is the whole answer for every endpoint of every named provider. Endpoint-level MARKUP overrides are preserved. Clients split larger selections into bounded batches so edge inspection cannot reject an oversized request. Batches commit independently: a failure after an earlier batch committed leaves that batch applied.
# Enable or disable a bounded set of slugs
Source: https://docs.paywithlocus.com/api-reference/catalog/enable-or-disable-a-bounded-set-of-slugs
/api-reference/openapi.json put /credits/catalog/batch
Enables or disables up to 50 slugs (provider ids or provider/endpoint) in one transaction, each with the row semantics of the single write: a provider entry converges its endpoint-level enablement overrides to inherit (and clears their MCP pins when it turns off); an endpoint entry writes its own row (and drops its own pin when it turns off). Markup overrides are preserved. Everything is validated before anything is written; entries apply in the order given; the response reports the effective enablement per entry. Open to personal accounts. Registered ahead of the provider routes, so batch is never read as a provider id.
# Enable/disable or override markup
Source: https://docs.paywithlocus.com/api-reference/catalog/enabledisable-or-override-markup
/api-reference/openapi.json put /credits/catalog/{slug}
slug is `provider` (whole provider) or `provider/endpoint` (URL-encoded). Personal accounts must send exactly `{"enabled": boolean}` and receive only endpointSlug plus effective enabled state; markup fields and extra properties are rejected. Enterprise workspaces may update enablement and/or markup. Enablement resolves endpoint override -> provider override -> platform default. Omitting enabled never changes enablement. Sending enabled on a provider slug resets that provider's endpoint-level enablement overrides to inherit while preserving markup overrides.
# Explain one endpoint's price
Source: https://docs.paywithlocus.com/api-reference/catalog/explain-one-endpoints-price
/api-reference/openapi.json get /credits/pricing/explain
Breaks one endpoint's price into base cost, percentage markup, flat markup, your margin, and the customer-visible effective price, and names which configuration level supplied each markup. Endpoints priced live per call return the honest variable shape with null money fields rather than a fabricated base.
# Get one full provider catalog document
Source: https://docs.paywithlocus.com/api-reference/catalog/get-one-full-provider-catalog-document
/api-reference/openapi.json get /credits/catalog/{slug}
Fetches executable endpoint schemas and the reviewed model inventory only for the selected provider. For this operation, slug must be one provider ID. Use after the compact list, not as a polling endpoint.
# List catalog with your effective prices
Source: https://docs.paywithlocus.com/api-reference/catalog/list-catalog-with-your-effective-prices
/api-reference/openapi.json get /credits/catalog
Use the default view=compact for normal enterprise catalog browsing. Compact responses omit executable JSON Schemas and model inventories, page providers, carry a version/ETag, and are gzip-compressed when the client advertises gzip. view=dashboard is the Locus Pro dashboard projection; its first page also publishes pageCursors so the dashboard can fetch the remaining pages concurrently. view=summary returns every provider as price-free card metadata and endpoint counts in one response. Agents should stay on compact and follow nextCursor; the 2026-08-31 revision only adds the optional provider secondaryCategories field, the 2026-09-05 revision adds `overridden` and `mcpPinned` to the dashboard endpoint plus the dashboard-only `enabled=true` filter, and the 2026-09-06 revision adds optional endpoint `billingModel` metadata. Personal accounts receive the price-safe dashboard projection when view is omitted or full/compact/dashboard is requested; they may also request summary. Request view=full only for the backward-compatible full export. Cache privately for at most 60 seconds and revalidate with If-None-Match; do not poll more often than once per minute.
# List live executable categories and curated packs
Source: https://docs.paywithlocus.com/api-reference/catalog/list-live-executable-categories-and-curated-packs
/api-reference/openapi.json get /credits/tools/groups
Returns principal-scoped group metadata and executable counts. Discovery does not enable tools or widen permissions.
# Put a journaled write back
Source: https://docs.paywithlocus.com/api-reference/catalog/put-a-journaled-write-back
/api-reference/openapi.json post /credits/catalog/changes/{requestId}/revert
Restores the rows one whole-catalog write moved, each to exactly what it held before (an explicit on or off, or inherit), and only where the write is still the last word on it: the row must read as the write left it (a turn-on left explicit on rows; a turn-off left provider rows off and the tool rows it converged at inherit) and no later write may have journaled the slug. Anything else was decided since and is skipped and counted, never clobbered. Rows are never deleted, so putting an earlier write back afterwards still finds them. A tool pinned now stays on and counts as skipped: putting a turn-on back never takes a pin away. Any other tool put back off drops its MCP pin; a tool put back on does not get its pin back, but pass the unpinned slugs the write answered with as repin and the answer names those that came back on. Only the id a whole-catalog write answered with (all-on:… or all-off:…) is accepted: other writers converge exceptions their journals do not record, so their state cannot be rebuilt exactly. The revert is journaled like any other write, under this request's id.
# Quote one described tool
Source: https://docs.paywithlocus.com/api-reference/catalog/quote-one-described-tool
/api-reference/openapi.json post /credits/tools/estimate
Prices the intended request without dispatching it or burning credits. Variable-price and live external-rail tools may return an executable approval token or request a hard maximum before execution.
# Read a tool access approval request
Source: https://docs.paywithlocus.com/api-reference/catalog/read-a-tool-access-approval-request
/api-reference/openapi.json post /credits/tool-access-requests/context
Requires a signed-in member of the requested workspace. The request token selects the workspace, independently of the dashboard workspace selection.
# Read the reviewed inference model contract
Source: https://docs.paywithlocus.com/api-reference/catalog/read-the-reviewed-inference-model-contract
/api-reference/openapi.json get /credits/models/{provider}
Returns Locus-supported model IDs, exact pricing dimensions, limits, route capabilities, request-field compatibility, deprecation state, and freshness metadata. This is a reviewed support boundary, not a pass-through of the provider's account-scoped model list.
# Recent enablement changes with who made them
Source: https://docs.paywithlocus.com/api-reference/catalog/recent-enablement-changes-with-who-made-them
/api-reference/openapi.json get /credits/catalog/changes
The newest catalog enablement changes first: which tool or provider moved, from what to what, who did it (a member by email, an API key by name, an agent connection by name) and through which surface. Rows are written inside the transaction that moved the enablement and only when the state actually changed; the journal is append-only.
# Request access to a disabled tool
Source: https://docs.paywithlocus.com/api-reference/catalog/request-access-to-a-disabled-tool
/api-reference/openapi.json post /credits/tools/access-requests
Return approval_url to a human workspace member. Creating a request does not enable the tool. MCP clients use request_tool_access instead.
# Search executable and requestable tools
Source: https://docs.paywithlocus.com/api-reference/catalog/search-executable-and-requestable-tools
/api-reference/openapi.json post /credits/tools/search
REST counterpart to MCP search_apis. Returns compact ranked summaries and routes a selected result through /credits/tools/describe. Workspace and agent principals see enabled and requestable disabled tools by default; end-user-bound callers see enabled tools only, and an account setting may choose enabled-only discovery. Results honor key endpoint allowlists, agent-connection scopes, and end-user policies. Secret keys require tenant:read rather than credits:move. This operation does not call a provider or burn credits.
# Search the management catalog
Source: https://docs.paywithlocus.com/api-reference/catalog/search-the-management-catalog
/api-reference/openapi.json post /credits/catalog/search
Searches the built-in account-visible management catalog, including endpoints that are currently disabled. Enterprise-owned Custom APIs remain available through the catalog listing and detail routes but are not included in this static search index. Returns price-free display metadata, desired enablement, and current platform availability so a dashboard can help a person choose tools before enabling them. Always-on system routes are omitted; a tenant-toggleable Locus Travel route is included when available. This operation does not call a provider or burn credits.
# Set the workspace default markup
Source: https://docs.paywithlocus.com/api-reference/catalog/set-the-workspace-default-markup
/api-reference/openapi.json put /credits/catalog
Sets the tenant-wide default percentage and flat markup applied to every endpoint that has no provider or endpoint override. This is the base of the three-level precedence endpoint over provider over global that GET /credits/pricing/explain reports as markupSource. Send either field alone to change just that one; null restores the platform default.
# Turn every mutable tool on or off
Source: https://docs.paywithlocus.com/api-reference/catalog/turn-every-mutable-tool-on-or-off
/api-reference/openapi.json put /credits/catalog/all
Moves every tool the workspace can switch in one transaction. enabled: true writes tool rows only: provider-level rows never move, so a tool added to a provider later still starts off. enabled: false writes every provider with a tool on at provider scope, resetting its endpoint-level enablement overrides to inherit and clearing their MCP pins, exactly as a provider entry of the batch route does. Markup overrides are preserved; always-on tools and custom endpoints are untouched. Every mutable provider is locked first, in one statement. The write is journaled under a fresh request id of its own, never the caller's x-request-id, and the response returns it so POST /credits/catalog/changes/{requestId}/revert can put exactly this write back. Open to personal accounts. Registered ahead of the provider routes, so all is never read as a provider id.
# Create a custom API provider
Source: https://docs.paywithlocus.com/api-reference/custom-apis/create-a-custom-api-provider
/api-reference/openapi.json post /credits/custom-endpoints
Creates one BYOK provider and optionally up to 50 actions atomically. Requires an enterprise workspace with Custom APIs enabled, the workspace owner, credentials:manage and catalog:write, plus MFA or passkey step-up completed in the last ten minutes. Locus validates the upstream URL against SSRF controls, encrypts the credential, validates every JSON Schema and example, and never returns the raw credential.
# Create an action for a custom provider
Source: https://docs.paywithlocus.com/api-reference/custom-apis/create-an-action-for-a-custom-provider
/api-reference/openapi.json post /credits/custom-endpoints/{providerId}/endpoints
Creates one disabled-by-default or explicitly enabled action. Its input schema must describe an object, its example must validate, path placeholders must resolve to scalar schema properties, and the top-level names externalUserId, attribution, and _locus are reserved for Locus transport controls. Publishing an enabled action requires a positive end-user price.
# Delete a custom API action
Source: https://docs.paywithlocus.com/api-reference/custom-apis/delete-a-custom-api-action
/api-reference/openapi.json delete /credits/custom-endpoints/{providerId}/endpoints/{endpointId}
Permanently removes one custom action. Requires the enterprise owner with credentials:manage, catalog:write, and recent step-up.
# Delete a custom API provider
Source: https://docs.paywithlocus.com/api-reference/custom-apis/delete-a-custom-api-provider
/api-reference/openapi.json delete /credits/custom-endpoints/{providerId}
Permanently removes the provider, its encrypted upstream credential, and its custom actions. Requires the same enterprise owner, scope, and recent step-up controls as creation.
# List custom API providers and actions
Source: https://docs.paywithlocus.com/api-reference/custom-apis/list-custom-api-providers-and-actions
/api-reference/openapi.json get /credits/custom-endpoints
Feature-gated enterprise management surface. Requires catalog:write. The raw upstream credential is never returned. Only a workspace owner whose credential also has credentials:manage receives the provider base URL and redacted authentication metadata; every other authorized caller receives null for those upstream configuration fields.
# Update a custom API action
Source: https://docs.paywithlocus.com/api-reference/custom-apis/update-a-custom-api-action
/api-reference/openapi.json patch /credits/custom-endpoints/{providerId}/endpoints/{endpointId}
Updates one action without changing its stable slug. Contract and pricing changes are revalidated; a pricing change increments pricingRevision. Requires the enterprise owner with credentials:manage, catalog:write, and recent step-up.
# Update a custom API provider
Source: https://docs.paywithlocus.com/api-reference/custom-apis/update-a-custom-api-provider
/api-reference/openapi.json patch /credits/custom-endpoints/{providerId}
Updates provider presentation, SSRF-checked base URL, authentication, or traffic protection. Supplying a new credential rotates the encrypted secret; type=none removes it. Requires the same enterprise owner, scope, and recent step-up controls as creation.
# Allocate credits to an end-user
Source: https://docs.paywithlocus.com/api-reference/end-users/allocate-credits-to-an-end-user
/api-reference/openapi.json post /credits/end-users/{externalUserId}/allocate
Atomic platform-pool → end-user transfer; both sides ledgered. Fails (402) if the pool cannot cover it — unfunded allocations are impossible. Amounts are exact decimal strings.
# Create or replace an end user's execution policy
Source: https://docs.paywithlocus.com/api-reference/end-users/create-or-replace-an-end-users-execution-policy
/api-reference/openapi.json put /credits/end-users/{externalUserId}/policy
Workspace owner/admin session or a secret key with tokens:manage. Admission, counters, the credit hold, and the reservation commit atomically. Amounts use the tenant's exact credit denomination.
# List an end user's minted tokens
Source: https://docs.paywithlocus.com/api-reference/end-users/list-an-end-users-minted-tokens
/api-reference/openapi.json get /credits/end-users/{externalUserId}/tokens
Token metadata for one end user, newest first, capped at 200 records. Use it to audit what is outstanding and to find the tokenId to revoke. The tokens themselves are returned only at mint time and are never recoverable.
# List end-users with balances
Source: https://docs.paywithlocus.com/api-reference/end-users/list-end-users-with-balances
/api-reference/openapi.json get /credits/end-users
# List policy allow, deny, capture, release, and reset decisions
Source: https://docs.paywithlocus.com/api-reference/end-users/list-policy-allow-deny-capture-release-and-reset-decisions
/api-reference/openapi.json get /credits/end-users/{externalUserId}/policy/events
# Mint an end-user token
Source: https://docs.paywithlocus.com/api-reference/end-users/mint-an-end-user-token
/api-reference/openapi.json post /credits/end-users/{externalUserId}/token
Mint server-side only. Creates the tenant-scoped end-user record and credit account on first use. JWT claims are sub, tid, iss=locus-credits, aud=locus-credits-enduser, iat, exp, jti, and optional sid. The sid claim is a SHA-256 fingerprint, not the raw session value. Verification allows 30 seconds of clock skew. There is no refresh token; re-authenticate the user and mint a replacement. A sid-bound token requires the original value in X-Locus-Session-Id whenever used.
# Public JWKS for end-user tokens
Source: https://docs.paywithlocus.com/api-reference/end-users/public-jwks-for-end-user-tokens
/api-reference/openapi.json get /credits/.well-known/end-user-jwks.json
RS256 public keys for verifying end-user tokens yourself, keyed by the token's kid claim. Public and cacheable for 5 minutes. Revoked signing keys are never published, so a token signed by a retired key fails verification here exactly as it does server-side.
# Read an immutable end user's execution policy
Source: https://docs.paywithlocus.com/api-reference/end-users/read-an-immutable-end-users-execution-policy
/api-reference/openapi.json get /credits/end-users/{externalUserId}/policy
# Reset an end user's execution policy to no policy
Source: https://docs.paywithlocus.com/api-reference/end-users/reset-an-end-users-execution-policy-to-no-policy
/api-reference/openapi.json delete /credits/end-users/{externalUserId}/policy
Workspace owner/admin session or a secret key with tokens:manage. Deletes operational policy counters only after all live reservations have captured or released. The append-only policy decision journal remains queryable by account. Repeating a completed reset is safe and returns reset=false.
# Retire a test or integration end user without deleting financial history
Source: https://docs.paywithlocus.com/api-reference/end-users/retire-a-test-or-integration-end-user-without-deleting-financial-history
/api-reference/openapi.json delete /credits/end-users/{externalUserId}
Workspace owner or admin with fresh MFA/passkey step-up only. Fails closed unless the balance is zero and every reservation, top-up attempt, external purchase, and refund is terminal. Revokes end-user tokens and scoped agent credentials, cancels outstanding approvals, resets the operational policy, freezes the credit account, and marks the identity inactive. Ledger, funding, settlement, replay, and audit rows are retained. Repeating a completed retirement is safe.
# Reverse an allocation
Source: https://docs.paywithlocus.com/api-reference/end-users/reverse-an-allocation
/api-reference/openapi.json post /credits/end-users/{externalUserId}/deallocate
# Revoke an end-user token
Source: https://docs.paywithlocus.com/api-reference/end-users/revoke-an-end-user-token
/api-reference/openapi.json delete /credits/end-users/{externalUserId}/tokens/{tokenId}
Revokes one outstanding end-user token by its durable jti. Revocation takes effect immediately on the next use, which is the only way to cut a leaked token short — bearer tokens are otherwise replayable until they expire.
# Archive a Workflow definition
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/archive-a-workflow-definition
/api-reference/openapi.json post /credits/workflows/{workflowId}/archive
# Clone a Workflow draft
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/clone-a-workflow-draft
/api-reference/openapi.json post /credits/workflows/{workflowId}/clone
# Create a tenant-private Workflow draft
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/create-a-tenant-private-workflow-draft
/api-reference/openapi.json post /credits/workflows
# Get a Workflow draft and its recent validation/version history
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/get-a-workflow-draft-and-its-recent-validationversion-history
/api-reference/openapi.json get /credits/workflows/{workflowId}
# Inspect durable run state, metering, receipts, and artifact references
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/inspect-durable-run-state-metering-receipts-and-artifact-references
/api-reference/openapi.json get /credits/workflow-runs/{runId}
# List saved Workflow definitions
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/list-saved-workflow-definitions
/api-reference/openapi.json get /credits/workflows
# List tenant-owned Workflow runs
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/list-tenant-owned-workflow-runs
/api-reference/openapi.json get /credits/workflow-runs
# Queue a bounded pilot or production run
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/queue-a-bounded-pilot-or-production-run
/api-reference/openapi.json post /credits/workflows/{workflowId}/runs
Complete successful fixture tests for the exact source before starting a live pilot. A production run also requires a successful pilot of the same saved version. The run inherits and is bounded by the current connection.
# Read a bounded tenant-owned artifact page
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/read-a-bounded-tenant-owned-artifact-page
/api-reference/openapi.json get /credits/workflows/artifacts/{artifactId}
# Resume eligible unfinished work with current authorization
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/resume-eligible-unfinished-work-with-current-authorization
/api-reference/openapi.json post /credits/workflow-runs/{runId}/resume
# Save an immutable checked Workflow version
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/save-an-immutable-checked-workflow-version
/api-reference/openapi.json post /credits/workflows/{workflowId}/versions
# Stop new dispatch and request sandbox termination
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/stop-new-dispatch-and-request-sandbox-termination
/api-reference/openapi.json post /credits/workflow-runs/{runId}/cancel
# Structurally check or fixture-test an exact draft revision
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/structurally-check-or-fixture-test-an-exact-draft-revision
/api-reference/openapi.json post /credits/workflows/{workflowId}/validate
check does not evaluate user code. fixtures runs in the fixed sandbox without live gateway authority or egress.
# Update a Workflow draft with optimistic concurrency
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/update-a-workflow-draft-with-optimistic-concurrency
/api-reference/openapi.json put /credits/workflows/{workflowId}
# Upload a tenant-owned source or input artifact
Source: https://docs.paywithlocus.com/api-reference/hosted-workflows/upload-a-tenant-owned-source-or-input-artifact
/api-reference/openapi.json post /credits/workflows/artifacts
Accepts authenticated JSON content up to the configured artifact ceiling. It never fetches caller-supplied URLs.
# API reference
Source: https://docs.paywithlocus.com/api-reference/introduction
Call paid APIs, manage credits, and build usage billing with Locus Pro Enterprise.
Use one API to access paid tools, track costs, and manage customer balances. Metered calls accept the provider's request body and return its response with the charge and remaining balance.
For a first integration, start with the [Enterprise quickstart](/locus-pro/enterprise/quickstart) or [Node SDK](/locus-pro/sdk). The reference pages provide request schemas, responses, and a live playground.
## Base URL
```text title="API origin" wrap theme={null}
https://api.paywithlocus.com
```
| Route | Purpose |
| -------------------------------------------- | --------------------------------------------------- |
| `/api/wrapped/credits/{provider}/{endpoint}` | Make a metered call |
| `/api/credits/*` | Manage the catalog, balances, funding, and accounts |
| `/api/credits/mcp` | Connect an agent through MCP |
## Find and call a tool
Call `POST /api/credits/tools/search` with a task, category, or Tool Pack.
Send the selected slug to `POST /api/credits/tools/describe` for its
current inputs and access requirements.
Call `POST /api/credits/tools/estimate` for a quote or spending ceiling.
Call `POST /api/wrapped/credits/{provider}/{endpoint}`. Reuse the same
idempotency key for retries.
Search can include tools that need access approval. Discovery does not enable a tool or grant permission to call it.
## Recipes and Workflows
| Feature | Use it to |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [Recipes](/locus-pro/enterprise/recipes) | Search, research, extract, enrich, or compare flights; `/preview` routes plan without paid execution |
| [Workflows](/locus-pro/enterprise/workflows) | Create drafts, validate and save versions, start bounded runs, and retrieve results |
Use each Recipe's current input schema and credit ceiling. Workflow REST calls
use an enterprise server key or scoped Agent Connection; OAuth agents use MCP.
## Agent setup
`GET /api/credits/mcp/docs` returns the MCP URL, OAuth metadata, plugin installation commands, and client configurations. The plugin uses the same MCP connection and permissions.
## Authentication
| Client | Credential |
| --------------------------------- | ------------------------------------------------- |
| Trusted enterprise server | Secret key (`lcr_…`) |
| Hosted agent or background worker | Scoped Agent Connection (`lcac_…`) |
| Browser widget | Short-lived end-user token with a publishable key |
| Interactive MCP client | OAuth |
Server credentials use a bearer header:
```text title="Authorization header" wrap theme={null}
Authorization: Bearer
```
Keep secret keys on your server. An Agent Connection limits execution to its bound account and tools. Browser tokens authorize only their end user.
Locus Pro self-serve accounts connect through [MCP OAuth](/locus-pro/individual/connect-agents). Server management and widget APIs require Locus Pro Enterprise. [Agent-native onboarding](/locus-pro/agent-native-onboarding) has a separate public registration flow.
## Request conventions
* **Use decimal strings for money.** Send `"10.00"` for an amount, preserving precision.
* **Reuse idempotency keys on retries.** Paid calls and transfers require `Idempotency-Key`. A repeat returns the stored outcome; a changed request with the same key returns `409`.
* **Read cost headers.** Calls return `X-Locus-Credits-Charged` and `X-Locus-Credits-Balance`. Secret-key calls also return `X-Locus-Cost-Usd`.
* **Tag usage.** Send `X-Locus-Attribution` as a JSON object to associate ledger entries with a customer, task, or project.
Non-streaming failures before success release the credit reservation. Accepted streams remain charged if the client later disconnects. See [inference and streaming](/locus-pro/inference#dynamic-charges-and-streaming).
## Related guides
* [SDK reference](/locus-pro/sdk): calls, balances, funding, and connection management.
* [Connect an agent](/locus-pro/connect-agents): OAuth and scoped service credentials.
* [Framework integrations](/locus-pro/frameworks): examples for model SDKs and agent frameworks.
# Begin Stripe Connect onboarding
Source: https://docs.paywithlocus.com/api-reference/ledger/begin-stripe-connect-onboarding
/api-reference/openapi.json get /credits/connect/stripe/authorize
Returns the Stripe consent URL to send a workspace owner or admin to. Dashboard-only: a tenant secret key cannot start this flow, and evaluation workspaces are refused until a commercial agreement is active. Requires an owner or admin with MFA step-up completed in the last ten minutes.
# Commercial agreement and invoice history
Source: https://docs.paywithlocus.com/api-reference/ledger/commercial-agreement-and-invoice-history
/api-reference/openapi.json get /credits/billing/commercial
Read-only view of an activated enterprise agreement, the live estimate for the current period, and issued invoice history. Workspaces without a commercial agreement get the empty shape rather than an error.
# Disconnect Stripe and revert to USDC payouts
Source: https://docs.paywithlocus.com/api-reference/ledger/disconnect-stripe-and-revert-to-usdc-payouts
/api-reference/openapi.json post /credits/connect/stripe/disconnect
Unlinks the Stripe account and returns the workspace to USDC margin payouts. Dashboard-only, and requires a workspace owner or admin with MFA step-up completed in the last ten minutes.
# Ledger row counts for a filter
Source: https://docs.paywithlocus.com/api-reference/ledger/ledger-row-counts-for-a-filter
/api-reference/openapi.json get /credits/ledger/summary
Counts the rows GET /credits/ledger would page through under the same filters. Cursor pagination can report neither a total nor a per-category split, which the Activity pager and its type chips need.
# Margin earnings
Source: https://docs.paywithlocus.com/api-reference/ledger/margin-earnings
/api-reference/openapi.json get /credits/earnings
# Stripe Connect OAuth redirect target
Source: https://docs.paywithlocus.com/api-reference/ledger/stripe-connect-oauth-redirect-target
/api-reference/openapi.json get /credits/connect/stripe/callback
Stripe redirects the browser here after consent. Authorization comes from the signed state parameter rather than an Authorization header, so this route is deliberately public — do not call it yourself. It always answers with a 302 back to the dashboard, carrying connected=1 on success or connect_error= on failure or cancellation.
# Stripe Connect status for payouts
Source: https://docs.paywithlocus.com/api-reference/ledger/stripe-connect-status-for-payouts
/api-reference/openapi.json get /credits/connect/stripe/status
Whether this workspace is linked to a Stripe account for margin payouts, and whether Stripe currently permits payouts on it. Check this before switching payoutMethod to stripe.
# Tenant usage analytics
Source: https://docs.paywithlocus.com/api-reference/ledger/tenant-usage-analytics
/api-reference/openapi.json get /credits/analytics
Exact database rollups over captured BURN debits. Accepts either the legacy days=7|30|90 form or an explicit half-open from/to window, optionally bucketed and narrowed to one spender and/or one provider. The prior comparison covers the same elapsed span as the current period, including today's partial UTC day, and is narrowed by the same filter so deltas stay like-for-like; top-ups, allocations, refunds, and open reservations are excluded. usageDrift is null when the optional detector read is temporarily unavailable.
# Tenant-wide ledger
Source: https://docs.paywithlocus.com/api-reference/ledger/tenant-wide-ledger
/api-reference/openapi.json get /credits/ledger
# Approve or deny an MCP device authorization
Source: https://docs.paywithlocus.com/api-reference/mcp/approve-or-deny-an-mcp-device-authorization
/api-reference/openapi.json post /credits/mcp/oauth/device/decision
Resolves one pending device request for the explicitly selected active membership. Approval reserves connection-plan capacity until the client exchanges the device code or the 15-minute request expires. A same-client retry by the same person supersedes its unfinished reservation.
# Complete AgentID login for a pending MCP authorization
Source: https://docs.paywithlocus.com/api-reference/mcp/complete-agentid-login-for-a-pending-mcp-authorization
/api-reference/openapi.json get /credits/mcp/oauth/agentid/callback
Verifies the AgentID Authorization Code response, binds the already activated agent-owned account, enforces its active-client limit, and redirects an MCP authorization code to the exact registered client callback.
# Continue a pending MCP authorization with AgentID
Source: https://docs.paywithlocus.com/api-reference/mcp/continue-a-pending-mcp-authorization-with-agentid
/api-reference/openapi.json get /credits/mcp/oauth/authorize/agentid
Builds the AgentID Authorization Code + PKCE request for a pending Locus MCP authorization and redirects to AgentID. AgentID is the resource-owner login for an already activated agent-owned account.
# Delete a dynamic MCP client registration
Source: https://docs.paywithlocus.com/api-reference/mcp/delete-a-dynamic-mcp-client-registration
/api-reference/openapi.json delete /credits/mcp/oauth/register/{clientId}
Deletes the registration and revokes its active authorization and token families.
# Discover the MCP authorization server
Source: https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-authorization-server
/api-reference/openapi.json get /.well-known/oauth-authorization-server/api/credits/mcp/oauth
Canonical RFC 8414 path derived from the MCP OAuth issuer.
# Discover the MCP authorization server (compatibility alias)
Source: https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-authorization-server-compatibility-alias
/api-reference/openapi.json get /credits/mcp/oauth/.well-known/oauth-authorization-server
API-prefixed compatibility alias for the canonical RFC 8414 metadata path.
# Discover the MCP protected resource
Source: https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-protected-resource
/api-reference/openapi.json get /.well-known/oauth-protected-resource/api/credits/mcp
Canonical RFC 9728 path derived from the MCP resource identifier.
# Discover the MCP protected resource (compatibility alias)
Source: https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-protected-resource-compatibility-alias
/api-reference/openapi.json get /credits/mcp/.well-known/oauth-protected-resource
API-prefixed compatibility alias for the canonical RFC 9728 metadata path.
# Dynamically register an MCP OAuth client
Source: https://docs.paywithlocus.com/api-reference/mcp/dynamically-register-an-mcp-oauth-client
/api-reference/openapi.json post /credits/mcp/oauth/register
RFC 7591 registration for public native or web clients. Register authorization_code with validated redirect URIs, the RFC 8628 device-code grant without redirect URIs, or both. refresh_token is optional; offline_access is grantable only when it is registered.
# Exchange or refresh an MCP OAuth token
Source: https://docs.paywithlocus.com/api-reference/mcp/exchange-or-refresh-an-mcp-oauth-token
/api-reference/openapi.json post /credits/mcp/oauth/token
Public-client token endpoint. Client secrets and Authorization headers are not supported. Authorization-code exchange requires the PKCE verifier; device clients poll no faster than the returned interval and handle authorization_pending, slow_down, access_denied, and expired_token; refresh tokens rotate on every successful use.
# Hosted MCP server (stateless Streamable HTTP)
Source: https://docs.paywithlocus.com/api-reference/mcp/hosted-mcp-server-stateless-streamable-http
/api-reference/openapi.json post /credits/mcp
One MCP JSON-RPC request per POST, with an encoded JSON body limit of 4 MiB. OAuth 2.1 is the primary authentication path: initialize, discovery, and resource reads require mcp:read, while billed tools/call execution additionally requires mcp:execute. Tenant secret keys, end-user JWTs, and scoped agent connections remain compatibility credentials. This transport is stateless: it issues no MCP-Session-Id, retains no resumable SSE stream, and recomputes the authenticated tenant catalog on every request. For tools/call, inspect result.isError even when HTTP and JSON-RPC both succeeded.
# List memberships available to a device authorization
Source: https://docs.paywithlocus.com/api-reference/mcp/list-memberships-available-to-a-device-authorization
/api-reference/openapi.json get /credits/mcp/oauth/device/tenants
Signed-in consent helper. Returns active Locus Pro memberships so a person with more than one account can make an explicit selection. It does not approve the device.
# Machine-readable MCP connection guide
Source: https://docs.paywithlocus.com/api-reference/mcp/machine-readable-mcp-connection-guide
/api-reference/openapi.json get /credits/mcp/docs
Public connection guide with the MCP URL, OAuth discovery metadata, plugin installation commands, and client configuration. Plugin installation uses these published commands; it does not require a separate plugin-management API.
# Read a dynamic MCP client registration
Source: https://docs.paywithlocus.com/api-reference/mcp/read-a-dynamic-mcp-client-registration
/api-reference/openapi.json get /credits/mcp/oauth/register/{clientId}
# Read safe signed-out context for an MCP authorization
Source: https://docs.paywithlocus.com/api-reference/mcp/read-safe-signed-out-context-for-an-mcp-authorization
/api-reference/openapi.json get /credits/mcp/oauth/authorize/public-context
Returns the non-sensitive client, scope, resource, expiry, and AgentID continuation URL for a pending OAuth request. Browserless agent-owned accounts use this endpoint after the MCP client starts Authorization Code + PKCE; it exposes no tenant or identity information.
# Read signed-in device consent context
Source: https://docs.paywithlocus.com/api-reference/mcp/read-signed-in-device-consent-context
/api-reference/openapi.json get /credits/mcp/oauth/device/context
Returns the selected account, grantable scopes, connection capacity, resource, and expiry immediately before a human approves or denies the device. Requested scopes may be reduced to the member's effective authority.
# Read signed-out device authorization context
Source: https://docs.paywithlocus.com/api-reference/mcp/read-signed-out-device-authorization-context
/api-reference/openapi.json get /credits/mcp/oauth/device/public-context
Returns only the pending client's public name, ID, requested scopes, resource, and expiry for a valid user code. It exposes no Locus identity, membership, or tenant data.
# Read the Locus MCP AgentID client descriptor
Source: https://docs.paywithlocus.com/api-reference/mcp/read-the-locus-mcp-agentid-client-descriptor
/api-reference/openapi.json get /credits/mcp/oauth/agentid/client
# Replace a dynamic MCP client registration
Source: https://docs.paywithlocus.com/api-reference/mcp/replace-a-dynamic-mcp-client-registration
/api-reference/openapi.json put /credits/mcp/oauth/register/{clientId}
# Revoke an MCP OAuth token family
Source: https://docs.paywithlocus.com/api-reference/mcp/revoke-an-mcp-oauth-token-family
/api-reference/openapi.json post /credits/mcp/oauth/revoke
RFC 7009-style public-client revocation. Revoking an access or refresh token revokes its token family; unknown tokens still return success.
# Start MCP device authorization
Source: https://docs.paywithlocus.com/api-reference/mcp/start-mcp-device-authorization
/api-reference/openapi.json post /credits/mcp/oauth/device_authorization
RFC 8628 authorization for a headless public client registered with the device-code grant. Send the exact MCP resource. Locus returns a 15-minute device code, a human-readable user code, and a five-second initial polling interval. Do not send client authentication.
# Start MCP OAuth authorization
Source: https://docs.paywithlocus.com/api-reference/mcp/start-mcp-oauth-authorization
/api-reference/openapi.json get /credits/mcp/oauth/authorize
Starts the public-client Authorization Code flow. PKCE S256 and the exact MCP resource indicator are required; the browser is redirected to Locus consent and then back to the registered redirect URI.
# Unsupported in stateless mode
Source: https://docs.paywithlocus.com/api-reference/mcp/unsupported-in-stateless-mode
/api-reference/openapi.json get /credits/mcp
# Unsupported in stateless mode
Source: https://docs.paywithlocus.com/api-reference/mcp/unsupported-in-stateless-mode-1
/api-reference/openapi.json delete /credits/mcp
# Bootstrap a scoped Locus CLI credential from Okibi Identity
Source: https://docs.paywithlocus.com/api-reference/okibi-identity/bootstrap-a-scoped-locus-cli-credential-from-okibi-identity
/api-reference/openapi.json post /credits/okibi/cli-credential
Exchanges a verified Okibi identity grant for one Locus lcac_ execution credential bound to the Okibi identity, CLI installation, and selected workspace. The credential expires 7 days after its last use and never later than 30 days after issue; every bootstrap issues it fresh for 7 days. Generate registrationToken locally from exactly 24 random bytes encoded as unpadded base64url. Replaying the token renews the installation's credential unchanged; a new token rotates that credential in place (same connection, new secret and prefix). A revoked credential is never renewed or rotated. When tools is present the server enables exactly those catalog slugs and restricts the credential to them; when it is omitted the credential may use every endpoint the workspace has enabled, and a fresh bootstrap may replace or lift an existing allowlist. The token is never stored; Locus stores only the derived credential hash.
# Read Okibi CLI credential bootstrap status
Source: https://docs.paywithlocus.com/api-reference/okibi-identity/read-okibi-cli-credential-bootstrap-status
/api-reference/openapi.json get /credits/okibi/cli-credential
A real Okibi-protected resource used to verify the signed CLI release, active identity grant, durable Locus account binding, and current installation credential state. It never returns the raw native credential. The account block names the linked Locus user and whether that user still has to choose a password. Requires both mcp:read and mcp:execute from Okibi Identity.
# Enable a provider for Recipes
Source: https://docs.paywithlocus.com/api-reference/recipes/enable-a-provider-for-recipes
/api-reference/openapi.json post /credits/router/providers/{providerId}/enable
Enterprise-only management update; requires catalog:write.
# Plan a multi-provider flight search without dispatching
Source: https://docs.paywithlocus.com/api-reference/recipes/plan-a-multi-provider-flight-search-without-dispatching
/api-reference/openapi.json post /wrapped/credits/locus-travel/flight-search/preview
Feature-gated Locus Travel planning route. It validates the normalized search, applies credential and catalog restrictions, selects eligible providers, and returns the aggregate estimated charge. It does not contact travel providers or burn credits. estimateExact is false when at least one selected provider has a live or otherwise variable price.
# Preview GTM Enrichment
Source: https://docs.paywithlocus.com/api-reference/recipes/preview-gtm-enrichment
/api-reference/openapi.json post /wrapped/credits/locus-gtm/enrich/preview
Plans enrichment and verification without calling providers or spending credits.
# Preview the saved multi-provider web-search plan
Source: https://docs.paywithlocus.com/api-reference/recipes/preview-the-saved-multi-provider-web-search-plan
/api-reference/openapi.json post /credits/router/preview
Enterprise-only free preview; requires tenant:read.
# Preview Web Extract
Source: https://docs.paywithlocus.com/api-reference/recipes/preview-web-extract
/api-reference/openapi.json post /wrapped/credits/router/web-extract/preview
Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.
# Preview Web Research
Source: https://docs.paywithlocus.com/api-reference/recipes/preview-web-research
/api-reference/openapi.json post /wrapped/credits/router/web-research/preview
Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.
# Preview Web Search
Source: https://docs.paywithlocus.com/api-reference/recipes/preview-web-search
/api-reference/openapi.json post /wrapped/credits/router/web-search/preview
Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.
# Read Recipe defaults and eligible providers
Source: https://docs.paywithlocus.com/api-reference/recipes/read-recipe-defaults-and-eligible-providers
/api-reference/openapi.json get /credits/router/settings
Enterprise-only management read; requires tenant:read.
# Read Recipes and provider availability
Source: https://docs.paywithlocus.com/api-reference/recipes/read-recipes-and-provider-availability
/api-reference/openapi.json get /wrapped/credits/router/capabilities
Returns the system-managed routing capabilities, saved settings, and current provider availability for the authenticated caller.
# Run GTM Enrichment
Source: https://docs.paywithlocus.com/api-reference/recipes/run-gtm-enrichment
/api-reference/openapi.json post /wrapped/credits/locus-gtm/enrich
Enriches a person or company record, verifies discovered contact data by default, and returns field sources and exact charges.
# Run Web Extract
Source: https://docs.paywithlocus.com/api-reference/recipes/run-web-extract
/api-reference/openapi.json post /wrapped/credits/router/web-extract
Reads the exact supplied URLs and returns their content and provider sources. Failed resources can use an extraction fallback.
# Run Web Research
Source: https://docs.paywithlocus.com/api-reference/recipes/run-web-research
/api-reference/openapi.json post /wrapped/credits/router/web-research
With effort set, returns a grounded answer with citations. Without effort, uses the legacy structured-source or multi-provider evidence contract.
# Run Web Search
Source: https://docs.paywithlocus.com/api-reference/recipes/run-web-search
/api-reference/openapi.json post /wrapped/credits/router/web-search
Searches eligible providers in parallel, canonicalizes and deduplicates URLs, fuses rankings, and returns per-result source provenance. The charge is the sum of successful underlying calls.
# Search flights across selected providers
Source: https://docs.paywithlocus.com/api-reference/recipes/search-flights-across-selected-providers
/api-reference/openapi.json post /wrapped/credits/locus-travel/flight-search
Feature-gated system-managed capability router. Locus plans eligible providers, executes them concurrently, normalizes and deduplicates itineraries, ranks offers, and returns aggregate billing. Use the preview route first when you need an estimate. A narrower request maxCredits or credential-level ceiling prevents dispatch when the aggregate estimate is too high. Retries must reuse the same Idempotency-Key and identical logical request; a 202 response means one or more child providers are still processing, so retry with the same key.
# Submit feedback for a completed flight search
Source: https://docs.paywithlocus.com/api-reference/recipes/submit-feedback-for-a-completed-flight-search
/api-reference/openapi.json post /wrapped/credits/locus-travel/flight-search/{runId}/feedback
Creates or replaces feedback for a completed run owned by the authenticated account. selectedItineraryId, when supplied, must belong to that run. End-user and Agent Connection access remains scoped exactly as it was for execution.
# Update Recipe defaults
Source: https://docs.paywithlocus.com/api-reference/recipes/update-recipe-defaults
/api-reference/openapi.json put /credits/router/settings
Enterprise-only management update. Legacy strategy is translated when mode is absent; legacy rails is accepted and ignored.
# Read monthly plan and Enterprise trial status
Source: https://docs.paywithlocus.com/api-reference/tenant/read-monthly-plan-and-enterprise-trial-status
/api-reference/openapi.json get /credits/plans
Requires a human workspace session with tenant:read. Trial expiry pauses Enterprise features without erasing prepaid balances or changing the assigned usage rate. Complete paid Enterprise checkout to restore those features; a top-up does not extend the trial.
# Accept an invitation as the matching signed-in identity
Source: https://docs.paywithlocus.com/api-reference/tenants/accept-an-invitation-as-the-matching-signed-in-identity
/api-reference/openapi.json post /credits/evaluation-invitations/accept-existing
The live Cognito email must exactly match the invited email. Successful acceptance selects the returned tenant with X-Locus-Tenant-Id.
# Create an evaluation account from a private invitation
Source: https://docs.paywithlocus.com/api-reference/tenants/create-an-evaluation-account-from-a-private-invitation
/api-reference/openapi.json post /credits/evaluation-invitations/accept
Creates the exact invited Cognito identity and atomically provisions one evaluation tenant and exactly $25 promotional credit. Existing identities must authenticate instead; this token is never a password-reset credential.
# Credential lifecycle audit
Source: https://docs.paywithlocus.com/api-reference/tenants/credential-lifecycle-audit
/api-reference/openapi.json get /credits/tenants/me/credentials/audit
Issue, rotate, and revoke events for API keys, agent connections, end-user tokens, and webhook secrets, newest first. Raw credentials and key hashes are never returned.
# Get tenant profile
Source: https://docs.paywithlocus.com/api-reference/tenants/get-tenant-profile
/api-reference/openapi.json get /credits/tenants/me
# Issue an independently scoped API key
Source: https://docs.paywithlocus.com/api-reference/tenants/issue-an-independently-scoped-api-key
/api-reference/openapi.json post /credits/tenants/me/keys
Creates an overlapping named credential. Requires a workspace owner or admin with credentials:manage and MFA or passkey step-up completed in the last ten minutes. A human caller cannot put a scope on a secret key that is absent from their own effective membership scopes. tools.enable narrows the tenant-enabled catalog for this key; pricing applies only to end-user calls and never widens tenant enablement. kind 'sandbox' issues a scopeless test credential (lcrsb_...) whose metered calls are simulated: no credits move and no providers are called. Unknown body fields are rejected with 400.
# List API-key metadata and immutable execution policies
Source: https://docs.paywithlocus.com/api-reference/tenants/list-api-key-metadata-and-immutable-execution-policies
/api-reference/openapi.json get /credits/tenants/me/keys
Raw keys and hashes are never returned; every caller sees lifecycle metadata including createdBy (issuer subject). Dashboard (Cognito) sessions additionally receive createdByEmail (workspace member email when the issuer is still a member) and usage (current-UTC-month burn attribution: monthUsdc, monthCalls — null for keys with no attributed burns; attribution began 2026-08 with the burn initiator envelope). Secret-key callers never receive those two enrichment fields: member emails and spend rollups stay behind a human session, matching the /members boundary. Results are bounded to 100 records and sorted newest first. Follow nextCursor until null.
# Read account spend and balance controls
Source: https://docs.paywithlocus.com/api-reference/tenants/read-account-spend-and-balance-controls
/api-reference/openapi.json get /credits/tenants/me/spend-controls
The account's monthly spend ceiling, spend-email threshold, low-balance threshold, and live position in the current UTC calendar-month window. Available to Personal and enterprise accounts. Read this before raising a limit: committedUsd, not spentUsd, is the figure enforced against the ceiling.
# Read the platform or end-user balance
Source: https://docs.paywithlocus.com/api-reference/tenants/read-the-platform-or-end-user-balance
/api-reference/openapi.json get /credits/balance
Returns the authenticated tenant's platform balance. Send X-Locus-End-User to read one end-user balance instead. Amounts are exact decimal strings in USD and the tenant's credit denomination.
# Rename an API key
Source: https://docs.paywithlocus.com/api-reference/tenants/rename-an-api-key
/api-reference/openapi.json patch /credits/tenants/me/keys/{keyId}
Metadata-only: the credential itself never changes. Appends a RENAMED credential audit event carrying the previous name. Requires a workspace owner or admin with MFA step-up completed in the last ten minutes.
# Resume interrupted self-serve workspace provisioning
Source: https://docs.paywithlocus.com/api-reference/tenants/resume-interrupted-self-serve-workspace-provisioning
/api-reference/openapi.json post /credits/tenants/self-serve
Recovery-only companion for a verified, authenticated Cognito identity. The token subject is the durable idempotency key: repeated calls return the same zero-credit workspace and cannot create another one.
# Revoke an API key
Source: https://docs.paywithlocus.com/api-reference/tenants/revoke-an-api-key
/api-reference/openapi.json delete /credits/tenants/me/keys/{keyId}
Revokes one key immediately; it returns 401 on the next request. Use this as the final step of a rotation, after the new credential is confirmed working. Requires a workspace owner or admin with MFA step-up completed in the last ten minutes.
# Rotate every active key of a kind (cutover)
Source: https://docs.paywithlocus.com/api-reference/tenants/rotate-every-active-key-of-a-kind-cutover
/api-reference/openapi.json post /credits/tenants/me/keys/rotate
Creates ONE replacement and supersedes ALL other active keys of that kind. Requires a workspace owner or admin with credentials:manage and MFA or passkey step-up completed in the last ten minutes. A human caller cannot delegate a secret-key scope absent from their own effective membership scopes. For rotating a single key while its siblings keep working, use POST /credits/tenants/me/keys/{keyId}/rotate.
# Rotate ONE key; sibling keys of the same kind keep working
Source: https://docs.paywithlocus.com/api-reference/tenants/rotate-one-key;-sibling-keys-of-the-same-kind-keep-working
/api-reference/openapi.json post /credits/tenants/me/keys/{keyId}/rotate
The replacement inherits the target's name, scopes, endpoint allowlist, pricing, audience (legacy policy-bearing rows are normalized to the execution audience), and — unless expiresIn is passed — its expiry deadline. A human caller cannot rotate a secret key whose inherited scopes include authority absent from their own effective membership scopes. Only the target is superseded: with gracePeriodSeconds > 0 it keeps authenticating until the overlap ends (capped at the target's own expiry), otherwise it is revoked with this response. Rotating a key that is already rotating out is rejected (rotate its replacement instead), as is rotating an expired key without a fresh expiresIn. This is the rotation the dashboard uses; the kind-level /keys/rotate remains the rotate-everything cutover. Requires a workspace owner or admin with MFA or passkey step-up completed in the last ten minutes.
# Sensitive-mutation security audit
Source: https://docs.paywithlocus.com/api-reference/tenants/sensitive-mutation-security-audit
/api-reference/openapi.json get /credits/tenants/me/security/audit
Append-only record of sensitive workspace mutations with actor, auth method, request id, source IP, outcome, and before/after state. Written before the success response, so a failed audit write fails the mutation. Newest first.
# Set or clear account spend and balance controls
Source: https://docs.paywithlocus.com/api-reference/tenants/set-or-clear-account-spend-and-balance-controls
/api-reference/openapi.json put /credits/tenants/me/spend-controls
Sets the monthly hard ceiling, monthly spend-email threshold, and/or low-balance email threshold. Send at least one field; omitted fields keep their current value and an explicit null clears one. Amounts are positive USD with at most 6 decimal places, up to 1000000000, and alertThresholdUsd may not exceed monthlyLimitUsd. Once committed spend reaches the ceiling, burns are denied with TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED until the window resets — the limit bounds new spend and never cancels in-flight calls. Personal changes require the account owner on a session authenticated within the last ten minutes; enterprise changes require a workspace owner or admin with MFA or passkey step-up in that window.
# Update tenant profile
Source: https://docs.paywithlocus.com/api-reference/tenants/update-tenant-profile
/api-reference/openapi.json patch /credits/tenants/me
Workspace owner/admin session or a secret key with tenant:write. Unknown fields are rejected atomically; recognized fields are never applied from a mixed known/unknown request. creditsPerDollar is immutable after provisioning and is rejected if supplied.
# Update tenant settings
Source: https://docs.paywithlocus.com/api-reference/tenants/update-tenant-settings
/api-reference/openapi.json put /credits/tenants/me
Workspace owner/admin sessions and secret keys with tenant:write may update webhookUrl or feeMode. A new webhookUrl is queued for an isolated ownership challenge; the previously verified URL remains active until that challenge succeeds. Requests containing marginPayoutAddress or payoutMethod require a dashboard session from a workspace owner or admin with MFA or passkey step-up completed in the last ten minutes; every other principal receives 403. Changing marginPayoutAddress starts a 24-hour payout hold.
# Validate an evaluation invitation
Source: https://docs.paywithlocus.com/api-reference/tenants/validate-an-evaluation-invitation
/api-reference/openapi.json post /credits/evaluation-invitations/validate
Returns only the company, masked email, expiry and safe invitation state. The raw token is never returned or logged.
# Execute a tool with an optional approved quote
Source: https://docs.paywithlocus.com/api-reference/tool-discovery/execute-a-tool-with-an-optional-approved-quote
/api-reference/openapi.json post /credits/tools/execute
Uses the same approval, spending limits, idempotency and billing result as MCP execute. Reuse the estimate approval_token and idempotency_key with the identical slug, customer and args. HTTP 200 means the execution envelope was delivered; inspect result.isError and its billing metadata before treating the call as successful. Sandbox credentials are not supported.
# Configure automatic balance reload
Source: https://docs.paywithlocus.com/api-reference/top-ups/configure-automatic-balance-reload
/api-reference/openapi.json post /credits/tenants/me/auto-recharge
Charges the saved card when the account's prepaid balance falls below thresholdUsd and credits amountUsd. Both fields must be positive and supplied together; send both as null to disable. Personal accounts call this auto-reload and require the account owner on a session authenticated within the last ten minutes. Enterprise workspaces call it auto-recharge and require a workspace owner or admin with payouts:manage plus recent MFA or passkey step-up. Evaluation workspaces may configure auto-recharge without activating a commercial agreement. Make one successful manual top-up first so Stripe has a reusable payment method.
# Create a hosted checkout session
Source: https://docs.paywithlocus.com/api-reference/top-ups/create-a-hosted-checkout-session
/api-reference/openapi.json post /credits/topups
Canonical v2 contract. externalUserId present → end-user top-up. Absent → platform-pool self-top-up. Send exactly one exact-decimal usd or credits amount. There is no fixed or daily platform top-up ceiling. Evaluation funding does not activate a commercial agreement.
# Get authoritative checkout state
Source: https://docs.paywithlocus.com/api-reference/top-ups/get-authoritative-checkout-state
/api-reference/openapi.json get /credits/topups/{sessionId}
# Get machine-readable top-up constraints
Source: https://docs.paywithlocus.com/api-reference/top-ups/get-machine-readable-top-up-constraints
/api-reference/openapi.json get /credits/topups/config
# List the account's payment history
Source: https://docs.paywithlocus.com/api-reference/top-ups/list-the-accounts-payment-history
/api-reference/openapi.json get /credits/tenants/me/topups
Returns only TOPUP ledger entries for the account's pooled balance, newest first. Available to Personal and enterprise accounts. Manual top-ups and automatic reloads are distinguished by entry metadata; this narrow history does not expose provider charges, end-user rows, or margin data.
# Quote a top-up (exact-decimal gross-up)
Source: https://docs.paywithlocus.com/api-reference/top-ups/quote-a-top-up-exact-decimal-gross-up
/api-reference/openapi.json post /credits/topups/quote
Send exactly one exact decimal string: usd or credits. Numeric compatibility values are deprecated. Declare externalUserId when the eventual create targets an end user so the bonus fields match the create.
# Top-up and Stripe ingress health
Source: https://docs.paywithlocus.com/api-reference/top-ups/top-up-and-stripe-ingress-health
/api-reference/openapi.json get /credits/stripe/operations
Operational health for this workspace's card funding: signed-webhook inbox state and recent top-up activity. Use it to tell a stuck top-up apart from a delivery backlog.
# Inspect an event and every delivery attempt
Source: https://docs.paywithlocus.com/api-reference/webhooks/inspect-an-event-and-every-delivery-attempt
/api-reference/openapi.json get /credits/webhooks/events/{eventId}
# List durable webhook events
Source: https://docs.paywithlocus.com/api-reference/webhooks/list-durable-webhook-events
/api-reference/openapi.json get /credits/webhooks/events
# Read the latest webhook ownership challenge
Source: https://docs.paywithlocus.com/api-reference/webhooks/read-the-latest-webhook-ownership-challenge
/api-reference/openapi.json get /credits/tenants/me/webhook-verification
Polling this endpoint never reveals or consumes the webhook signing secret.
# Replay a retained event
Source: https://docs.paywithlocus.com/api-reference/webhooks/replay-a-retained-event
/api-reference/openapi.json post /credits/webhooks/events/{eventId}/replay
Creates one new attempt using the same stable event ID and current endpoint. Returns 409 while another attempt is pending.
# Reveal the first verified webhook signing secret once
Source: https://docs.paywithlocus.com/api-reference/webhooks/reveal-the-first-verified-webhook-signing-secret-once
/api-reference/openapi.json post /credits/tenants/me/webhook-secret/reveal
Workspace owner/admin and MFA/passkey step-up protected. Status polling cannot consume this reveal. If it was already revealed, rotate the secret instead.
# Rotate the webhook signing secret
Source: https://docs.paywithlocus.com/api-reference/webhooks/rotate-the-webhook-signing-secret
/api-reference/openapi.json post /credits/tenants/me/webhook-secret/rotate
Returns the new secret once. Requires a workspace owner or admin with credentials:manage and MFA or passkey step-up completed in the last ten minutes. Deliveries contain signatures for both the current and previous secrets during a 24-hour overlap.
# Discover APIs available to the authenticated end user
Source: https://docs.paywithlocus.com/api-reference/widget/discover-apis-available-to-the-authenticated-end-user
/api-reference/openapi.json get /credits/me/catalog
Versioned cursor catalog. Returns only endpoints enabled by the tenant and allowed by this end user's current provider policy. Omitted endpoints do not reveal whether they are disabled, denied, or unknown. Tenant rules, base USD cost, markup, and margin are never returned; price.usd is the final customer-visible effective price. Results sort by stable endpoint ID. Cursors are opaque, filters are exact/case-insensitive, and responses are private/non-cacheable so policy changes are visible on the next request. The end-user token authenticates this read on its own; when a publishable key is sent it must belong to the token's tenant.
# Get authoritative state for this user's checkout
Source: https://docs.paywithlocus.com/api-reference/widget/get-authoritative-state-for-this-users-checkout
/api-reference/openapi.json get /credits/me/topups/{sessionId}
# Get machine-readable top-up constraints
Source: https://docs.paywithlocus.com/api-reference/widget/get-machine-readable-top-up-constraints
/api-reference/openapi.json get /credits/me/topups/config
# Open a top-up for self (end-user)
Source: https://docs.paywithlocus.com/api-reference/widget/open-a-top-up-for-self-end-user
/api-reference/openapi.json post /credits/me/topups
Identity is derived only from the end-user token. externalUserId is rejected.
# Own balance (end-user)
Source: https://docs.paywithlocus.com/api-reference/widget/own-balance-end-user
/api-reference/openapi.json get /credits/me/balance
# Own ledger (end-user)
Source: https://docs.paywithlocus.com/api-reference/widget/own-ledger-end-user
/api-reference/openapi.json get /credits/me/ledger
Returns newest-first transaction history for the end user encoded in the bearer token. The caller cannot select another externalUserId. Entries include charges, top-ups, allocations, refunds, and other posted balance movements. End-user responses redact base cost, markup, margin, tenant identifiers, and internal pricing configuration.
# Change a workspace member role
Source: https://docs.paywithlocus.com/api-reference/workspace-members/change-a-workspace-member-role
/api-reference/openapi.json patch /credits/members/{memberId}
Requires owner or admin membership, members:manage, and recent MFA or passkey step-up. The original owner cannot be reassigned and a member cannot change their own role.
# Create the invited identity and join its workspace
Source: https://docs.paywithlocus.com/api-reference/workspace-members/create-the-invited-identity-and-join-its-workspace
/api-reference/openapi.json post /credits/member-invitations/accept
Creates an account only for the exact invited email and joins the existing workspace. This is not a public account-creation surface. Existing identities must use the authenticated acceptance route.
# Invite people to a workspace
Source: https://docs.paywithlocus.com/api-reference/workspace-members/invite-people-to-a-workspace
/api-reference/openapi.json post /credits/member-invitations
Requires owner or admin membership, members:manage, and MFA or passkey step-up within the last ten minutes. Accepts at most 20 unique normalized email addresses.
# Join a workspace as the matching signed-in identity
Source: https://docs.paywithlocus.com/api-reference/workspace-members/join-a-workspace-as-the-matching-signed-in-identity
/api-reference/openapi.json post /credits/member-invitations/accept-existing
The live Cognito email must exactly match the invited email. The response identifies the workspace to select with X-Locus-Tenant-Id.
# List the signed-in person's workspace memberships
Source: https://docs.paywithlocus.com/api-reference/workspace-members/list-the-signed-in-persons-workspace-memberships
/api-reference/openapi.json get /credits/tenants
This discovery route does not require X-Locus-Tenant-Id. Use the selected tenantId as that header on subsequent dashboard management calls when the person belongs to multiple workspaces.
# List workspace members and pending invitations
Source: https://docs.paywithlocus.com/api-reference/workspace-members/list-workspace-members-and-pending-invitations
/api-reference/openapi.json get /credits/members
Human Cognito sessions only. Tenant API keys cannot enumerate workspace member email addresses.
# Remove a workspace member
Source: https://docs.paywithlocus.com/api-reference/workspace-members/remove-a-workspace-member
/api-reference/openapi.json delete /credits/members/{memberId}
Requires owner or admin membership, members:manage, and recent MFA or passkey step-up. The original owner cannot be removed and a member cannot remove their own current membership.
# Revoke a workspace invitation
Source: https://docs.paywithlocus.com/api-reference/workspace-members/revoke-a-workspace-invitation
/api-reference/openapi.json delete /credits/member-invitations/{invitationId}
Requires owner or admin membership, members:manage, and recent MFA or passkey step-up.
# Rotate and resend a pending workspace invitation
Source: https://docs.paywithlocus.com/api-reference/workspace-members/rotate-and-resend-a-pending-workspace-invitation
/api-reference/openapi.json post /credits/member-invitations/{invitationId}/resend
Requires owner or admin membership, members:manage, and recent MFA or passkey step-up. Rotating the token invalidates the previous email link.
# Validate a workspace invitation
Source: https://docs.paywithlocus.com/api-reference/workspace-members/validate-a-workspace-invitation
/api-reference/openapi.json post /credits/member-invitations/validate
Returns a masked-email preview for a single-use invitation token. The token is read from the email URL fragment and submitted in JSON so it does not enter normal access logs or referrers.
# Addons and domains
Source: https://docs.paywithlocus.com/build/addons-and-domains
Add a database, connect a cache, and put your app on its own domain.
Add Postgres or Redis to give your app persistent storage and caching. Attach a domain you own or buy one through Locus, with SSL included.
Your agent can manage both through the Build API, or you can use the dashboard.
## Available addons
| Addon | Use it for | Connection variable |
| ------------ | ---------------------------- | ------------------- |
| **Postgres** | Application data and queries | `DATABASE_URL` |
| **Redis** | Caching and shared state | `REDIS_URL` |
Each addon costs **\$0.25/month** from workspace credits.
## How addons work
Choose a name and your service's environment. Wait until the status is `available`: usually **30–60 seconds** for Postgres or **10–20 seconds** for Redis.
Add an explicit variable reference, such as `"DATABASE_URL": "${{db.DATABASE_URL}}"`. Only services that reference an addon receive its connection variables.
Deploy the service again to load the connection values.
See [variables and connections](/build/environment) for templates and the [addon reference](https://buildwithlocus.com/addons.md) for API requests, queries, and migrations.
## Custom domains
Every service already has a public HTTPS URL. Add a custom domain when you want your own address.
### Bring your own domain
Enter your domain in the dashboard. Locus provides a CNAME target and SSL certificate validation records.
Add the supplied records at your DNS provider, then verify the domain in Locus. DNS changes usually take 1–30 minutes.
Once DNS and the certificate validate, select the service that should receive the traffic.
### Purchase a domain
Search for a domain in the dashboard and review its price. Complete the purchase with your contact information, then attach it to a service once registration finishes. Registration usually takes **1–15 minutes**; Locus configures DNS and SSL automatically.
Use the [domain reference](https://buildwithlocus.com/domains.md) to have your agent search, purchase, verify, or attach a domain.
# Variables and connections
Source: https://docs.paywithlocus.com/build/environment
Configure your app and connect services to databases and each other.
Use environment variables for app settings, API keys, and database connections. Locus resolves them when you deploy, so services can find each other without hardcoded addresses.
Add variables in the dashboard or through the API. **Redeploy after changes** to make them available to your running app.
## Set variables
Use `PATCH` to add or update values while keeping existing variables:
```bash title="Update service variables" theme={null}
curl --fail-with-body -X PATCH \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"variables": {"LOG_LEVEL": "info"}}' \
"https://api.buildwithlocus.com/v1/variables/service/$SERVICE_ID"
```
`PUT` on the same route replaces all variables for the service. Keep secrets server-side and out of committed `.locusbuild` files.
## Service-to-service references
Locus injects sibling service URLs automatically. A service named `api` gives other services these variables:
| Variable | Use |
| ------------------- | ---------------------------------------------- |
| `API_URL` | Public HTTPS requests, including browser calls |
| `API_INTERNAL_URL` | Internal server-to-server requests |
| `LOCUS_SERVICE_URL` | The current service's own public URL |
Names are uppercased, with non-alphanumeric characters replaced by underscores.
## Template syntax
Use templates to connect a setting to a service or addon. For example, set `DATABASE_URL` to `${{db.DATABASE_URL}}` to connect to a Postgres addon named `db`.
| Template | Value |
| ------------------------------- | -------------------------- |
| `${{serviceName.URL}}` | Public service URL |
| `${{serviceName.INTERNAL_URL}}` | Internal service URL |
| `${{serviceName.PORT}}` | Service port |
| `${{addonName.DATABASE_URL}}` | Postgres connection string |
| `${{addonName.REDIS_URL}}` | Redis connection string |
Addon templates also expose `HOST` and `PORT`; Postgres adds `USERNAME` and `DATABASE`. Wait until the addon is `available` before deploying a service that references it.
Only services with explicit addon references receive those connection variables.
## Full-stack .locusbuild example
This connects an API to Postgres and Redis, and a frontend to the API:
```json .locusbuild theme={null}
{
"services": {
"api": {
"path": "backend",
"port": 8080,
"healthCheck": "/health",
"env": {
"DATABASE_URL": "${{db.DATABASE_URL}}",
"REDIS_URL": "${{cache.REDIS_URL}}",
"FRONTEND_URL": "${{web.URL}}"
}
},
"web": {
"path": "frontend",
"port": 8080,
"healthCheck": "/",
"env": {
"API_URL": "${{api.URL}}",
"API_INTERNAL_URL": "${{api.INTERNAL_URL}}"
}
}
},
"addons": {
"db": { "type": "postgres" },
"cache": { "type": "redis" }
}
}
```
## Variable scopes
When the same name exists in multiple scopes, **service variables** take priority over **environment variables**, which take priority over **addon variables**.
## Get resolved variables
Preview values before deploying:
```bash title="Preview resolved variables" theme={null}
curl --fail-with-body \
-H "Authorization: Bearer $TOKEN" \
"https://api.buildwithlocus.com/v1/variables/service/$SERVICE_ID/resolved"
```
Treat the response as sensitive; it can contain credentials. See the [Build API reference](https://buildwithlocus.com/api-reference.md) for all variable operations.
# Deploy with an agent
Source: https://docs.paywithlocus.com/build/for-agents
Ask your agent to deploy, update, and manage apps on Build with Locus.
Your agent can take a repository from local code to a live app, including databases and a domain. Send it the Build skill with the outcome you want:
```text theme={null}
Read https://buildwithlocus.com/SKILL.md and deploy this app with Build with Locus.
```
The skill contains authentication, API requests, and deployment instructions. You'll need a Locus API key or a workspace funded through [MPP](/build/mpp) or [x402](/build/x402).
## What to ask for
### Deploy a new app
> Deploy this GitHub repository to Build with Locus. Check its port and health endpoint, configure the required variables, and send me the live URL when the deployment is healthy.
Your agent creates a project and environment, configures the service, and monitors the build. GitHub and git-push builds typically take **3–7 minutes**; pre-built images take **1–2 minutes**.
### Add a database
> Add Postgres to this project's production environment. Connect it to the API service through DATABASE\_URL, run the app's migrations, and redeploy.
Locus provisions the database and exposes its connection values through [templates](/build/environment). Your agent adds the references and deploys the updated service.
### Ship an update
> Deploy the latest changes, check the health endpoint, and summarize what changed. If deployment fails, inspect the logs before retrying.
The API supports deployments, cancellations, rollbacks, restarts, and log access. You can follow progress in the dashboard.
## What you control
You choose the source code, environment, resources, and spending limits. Keep credentials in the agent's credential storage and application secrets in [service variables](/build/environment).
Ask your agent to report the final service URL, deployment status, and any action you need to take. For a failed deployment, the useful result is the error and next step.
## Companion guides
Your agent can load these public references when a task needs more detail:
| Guide | Covers |
| -------------------------------------------------------------------------- | ---------------------------------------- |
| [Quickstart](https://buildwithlocus.com/agent-quickstart.md) | Deploy scripts and setup |
| [Billing](https://buildwithlocus.com/billing.md) | Credits and payments |
| [Deployment workflows](https://buildwithlocus.com/deployment-workflows.md) | Deploy, cancel, rollback, and restart |
| [Monorepos](https://buildwithlocus.com/monorepo.md) | `.locusbuild` and multiple services |
| [Logs](https://buildwithlocus.com/logs.md) | Read, stream, and search logs |
| [Webhooks](https://buildwithlocus.com/webhooks.md) | Deployment and error notifications |
| [Addons](https://buildwithlocus.com/addons.md) | Postgres, Redis, queries, and migrations |
| [Domains](https://buildwithlocus.com/domains.md) | Connect or purchase a domain |
| [Git deploy](https://buildwithlocus.com/git-deploy.md) | Git remotes and GitHub auto-deploy |
| [API reference](https://buildwithlocus.com/api-reference.md) | Request and response details |
| [Troubleshooting](https://buildwithlocus.com/troubleshooting.md) | Failed builds and runtime issues |
# Getting started
Source: https://docs.paywithlocus.com/build/getting-started
Connect your account and deploy your first app with Build with Locus.
Send your agent the Build skill and tell it what to deploy:
```text title="Send to your agent" wrap theme={null}
Read https://buildwithlocus.com/SKILL.md and deploy this repository with Build with Locus.
```
Your agent can handle project setup, services, databases, and domains. The steps below show what you need and how to deploy directly through the API.
## Before you deploy
* Get a Locus API key from the [Agent Platform quickstart](/quickstart). If you already have a `claw_` key, reuse it.
* Make your app listen on **port 8080** and configure a health check that returns HTTP 200.
* For a private repository, connect GitHub at [buildwithlocus.com/integrations](https://buildwithlocus.com/integrations).
You can also create a workspace using [MPP on Tempo](/build/mpp) or [x402 on Base or Polygon](/build/x402).
## Authentication
Exchange your API key for a Build token:
```bash title="Get a Build token" theme={null}
TOKEN=$(curl --fail-with-body -sS -X POST https://api.buildwithlocus.com/v1/auth/exchange \
-H "Content-Type: application/json" \
-d '{"apiKey":"YOUR_LOCUS_API_KEY"}' | jq -er '.token')
```
Use `Authorization: Bearer $TOKEN` on subsequent Build API requests. Tokens last **30 days**; refresh through `POST /v1/auth/refresh`.
Keep keys and tokens server-side. Use [environment variables](/build/environment) for application secrets and keep them out of source control.
## Deploy your first service
For a GitHub repository, one request creates the project, environment, services, and deployments:
```bash title="Deploy a GitHub repository" theme={null}
curl --fail-with-body -sS -X POST https://api.buildwithlocus.com/v1/projects/from-repo \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "research-api",
"repo": "your-org/research-api",
"branch": "main"
}'
```
Replace `repo` with your repository. The response includes service URLs and deployment IDs. Locus reads a `.locusbuild` file if present; otherwise it creates a single `web` service.
Use a returned deployment ID to check progress:
```bash title="Check deployment status" theme={null}
curl --fail-with-body -sS \
-H "Authorization: Bearer $TOKEN" \
"https://api.buildwithlocus.com/v1/deployments/$DEPLOYMENT_ID"
```
Source builds typically take **3–7 minutes**. When the deployment is `healthy`, open the service URL. If it fails, inspect the deployment logs for the build or startup error.
## Git push deploys
To deploy local code, create a project and services, add the Locus remote, and push:
```bash title="Deploy local code" theme={null}
git remote add locus https://x:YOUR_API_KEY@git.buildwithlocus.com/{workspaceId}/{projectId}.git
git push locus main
```
Replace the key and IDs with your own values. Keep this remote private because it contains a credential. You can use a Build JWT in place of the API key.
A push deploys all services in the project. Each service uses its configured `rootDir`. See the [git deployment reference](https://buildwithlocus.com/git-deploy.md) for setup.
## Runtime configuration
| Setting | Default |
| ----------------- | --------------------- |
| Port | 8080 |
| CPU | 256 units (0.25 vCPU) |
| Memory | 512 MB |
| Minimum instances | 1 |
| Maximum instances | 3 |
Your app must read `PORT` or otherwise listen on 8080. Choose a health check path your app serves successfully. See [service configuration](/build/services#service-configuration).
## Build methods
Locus uses your Dockerfile when present, or automatic framework detection through Nixpacks or Railpack. You can also deploy a pre-built `linux/arm64` image.
## Multi-region support
Choose the region when creating your project. It applies to all services in that project.
| Region | Location |
| --------------------- | ----------------- |
| `us-east-1` (default) | Northern Virginia |
| `sa-east-1` | São Paulo |
## Pricing
| Resource | Cost |
| ----------------------- | --------------------------- |
| Service | \$0.25/month |
| Postgres or Redis addon | \$0.25/month |
| Domain | Price shown before purchase |
Service and addon charges are deducted from workspace credits on creation and renewed monthly. New Locus-linked workspaces start with **\$1.00** in credits. MPP and x402 sign-up offers are listed in their respective guides.
Manage credits in the dashboard, or check your balance with `GET /v1/billing/balance`. See the [billing reference](https://buildwithlocus.com/billing.md) for funding options.
## Next steps
Add [Postgres, Redis, or a domain](/build/addons-and-domains), configure [environment variables](/build/environment), or learn how to [manage deployments](/build/services).
# Build with Locus
Source: https://docs.paywithlocus.com/build/index
Give your agent a path from code to a live app.
Build with Locus lets your agent deploy apps, provision databases, and connect domains through an API. Give it a GitHub repository, local code, or a Docker image. Locus handles builds, containers, routing, and SSL.
Use it to ship a prototype, host an agent's API, or deploy a full-stack app. Follow deployments and manage resources from the dashboard.
## Deploy with your agent
Send your agent the [Build skill](https://buildwithlocus.com/SKILL.md) with a request like:
> Deploy this repository with Build with Locus. Add Postgres, configure the app's database connection, and send me the live URL when it's healthy.
Your agent sets up the project, configures services, and follows the deployment. The [getting started guide](/build/getting-started) covers credentials and your first deploy.
## What you get
* **Three deploy sources:** GitHub with automatic deploys, `git push` from a local repo, or a pre-built Docker image.
* **Managed databases:** Add Postgres or Redis and connect them through environment variables.
* **Public URLs and SSL:** Use the generated service URL or attach your own domain.
* **Separate environments:** Keep development, staging, and production in one project.
* **Deployment controls:** Inspect logs, cancel a deployment, restart a service, or roll back.
## How it works
Connect a GitHub repo, push local code, or provide a Docker image. Source builds can use your Dockerfile or automatic framework detection.
Set environment variables and add any databases. Your app must listen on port **8080** and expose a health check that returns HTTP 200.
Locus builds and starts your services. Once health checks pass, share the service URL or connect a domain.
## Key concepts
| Concept | What it holds |
| --------------- | --------------------------------------------------------------------- |
| **Project** | One codebase and its region. |
| **Environment** | Services and addons for development, staging, or production. |
| **Service** | One running container, with its source, configuration, and variables. |
| **Deployment** | A build and release of a service. |
| **Addon** | A managed Postgres database or Redis cache. |
## Pricing
Services and addons each cost **\$0.25/month**, paid from workspace credits. Domain prices vary by TLD. See [pricing and credits](/build/getting-started#pricing).
## Next steps
Connect your account and deploy your first service.
Choose a source and manage releases.
Connect services and databases.
Add storage and a public domain.
# MPP payments
Source: https://docs.paywithlocus.com/build/mpp
Create and fund a Build workspace from a Tempo wallet.
Use **USDC on Tempo** to create a Build with Locus workspace and add deployment credits through MPP. Your agent can set up the workspace from its wallet, then use the Build API to deploy apps.
Sign-up costs **$0.001 USDC**. Add credits before creating services; MPP workspaces start with **$0.00**.
## How it works
1. Your agent calls the MPP sign-up endpoint with its payment authorization.
2. Locus finds or creates the workspace for that wallet.
3. The response includes a **30-day JWT** for Build API requests.
4. You can follow the claim link to connect your email and access the dashboard.
## Sign up via MPP
MPP requests use `https://mpp.buildwithlocus.com/v1`:
```bash theme={null}
curl --fail-with-body -sS -X POST https://mpp.buildwithlocus.com/v1/auth/mpp-sign-up \
-H "Content-Type: application/json" \
-H "Payment: "
```
Your MPP client supplies the payment header. A successful response includes `jwt`, `workspaceId`, and, for a new external wallet, `claimUrl`.
Use the JWT as a Bearer token for deployment calls to `https://api.buildwithlocus.com/v1`. Send your agent the [Build skill](https://buildwithlocus.com/SKILL.md) for the full authentication contract.
## Top up credits via MPP
Use `POST /v1/billing/mpp-top-up` on the MPP host with your Bearer token, payment header, and requested amount:
```bash theme={null}
curl --fail-with-body -sS -X POST https://mpp.buildwithlocus.com/v1/billing/mpp-top-up \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Payment: " \
-d '{"amount": 5.00}'
```
Check `creditBalance` in the response before deploying. See [billing](https://buildwithlocus.com/billing.md) for credit management.
## Claim links
Open the returned `claimUrl` to connect your email to the workspace and use the dashboard. Your agent can continue deploying with its JWT before you claim it.
## Git push deploys with MPP
Use the JWT as the password in your Locus git remote:
```bash theme={null}
git remote add locus https://x:$JWT_TOKEN@git.buildwithlocus.com/{workspaceId}/{projectId}.git
git push locus main
```
Replace the workspace and project IDs with your own. Keep the credential-bearing remote private.
## Network details
| Detail | Value |
| -------------- | ----------------------------------- |
| Chain | Tempo, ID `4217` |
| Token | USDC on Tempo |
| MPP host | `https://mpp.buildwithlocus.com/v1` |
| Client library | `mppx` |
For wallets on Base or Polygon, use [x402](/build/x402).
# Services and deployments
Source: https://docs.paywithlocus.com/build/services
Deploy from GitHub, local code, or a Docker image and manage each release.
A service runs one part of your app, such as a frontend or API. Each service gets a public HTTPS URL, runtime settings, environment variables, and a deployment history.
Services cost **\$0.25/month** from workspace credits. Use one project per codebase, with separate environments for development, staging, and production.
## Choosing a deploy method
| Source | Best for | How to deploy |
| ------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| GitHub | A repository hosted on GitHub | Use `POST /v1/projects/from-repo` to create the project and deploy in one request. |
| Local code | A local repository or CI pipeline | Create the project and services, then [push to the Locus remote](/build/getting-started#git-push-deploys). |
| Docker image | An image you've already built | Create a service with `source.type: "image"` and an `imageUri`. |
GitHub and git-push sources support automatic builds. Pre-built images must target **`linux/arm64`**.
## Creating a service
For GitHub, start with:
```bash title="Deploy a GitHub repository" theme={null}
curl --fail-with-body -sS -X POST https://api.buildwithlocus.com/v1/projects/from-repo \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "research-api",
"repo": "your-org/research-api",
"branch": "main"
}'
```
Replace `repo` with your repository. Connect private repositories through [GitHub integrations](https://buildwithlocus.com/integrations) first. See [authentication](/build/getting-started#authentication) to get `$TOKEN`.
Locus reads `.locusbuild` when present, or creates a single `web` service. The response includes the project, environment, services, and deployments. Set `autoDeploy: true` on a GitHub service to deploy each push to its configured branch.
For manual service creation or a pre-built image, use `POST /v1/services`. Request fields are in the [API reference](https://buildwithlocus.com/api-reference.md).
## Service configuration
Your container must listen on **port 8080**. Locus sets `PORT=8080`. Configure a health check path that returns HTTP 200.
| Setting | Default | Purpose |
| ----------------- | --------- | ---------------------------------------- |
| `port` | 8080 | Container port |
| `cpu` | 256 | CPU units; 256 is 0.25 vCPU |
| `memory` | 512 | Memory in MB |
| `minInstances` | 1 | Minimum running containers |
| `maxInstances` | 3 | Maximum running containers |
| `startCommand` | Image CMD | Override the container's startup command |
| `healthCheckPath` | `/` | Readiness endpoint |
Keep secrets in [environment variables](/build/environment). For custom Dockerfile paths, build arguments, and error monitoring, use the [service API reference](https://buildwithlocus.com/api-reference.md).
## Service URL
The creation response includes your service's `url`, for example `https://svc-abc123.buildwithlocus.com`. Service URLs support HTTPS and WebSockets. You can also [attach a custom domain](/build/addons-and-domains#custom-domains).
## Deployment lifecycle
| Status | Meaning |
| ---------------- | --------------------------------------------- |
| **queued** | Waiting for a build worker |
| **building** | Building an image from source |
| **deploying** | Starting containers and running health checks |
| **healthy** | Running and passing health checks |
| **failed** | Build or startup failed; inspect the logs |
| **cancelled** | Deployment was cancelled |
| **rolled\_back** | Replaced by a rollback deployment |
Image deployments skip the build step. Source builds typically take **3–7 minutes**, and pre-built images take **1–2 minutes**.
## Monitor a deployment
Follow progress in the dashboard or fetch a deployment by ID:
```bash title="Check deployment status" theme={null}
curl --fail-with-body -sS \
-H "Authorization: Bearer $TOKEN" \
"https://api.buildwithlocus.com/v1/deployments/$DEPLOYMENT_ID"
```
Check about once a minute until it finishes. Failed deployments include recent logs. For running container counts, use `GET /v1/services/:id?include=runtime`.
To cancel, roll back, restart, or redeploy, see the [deployment reference](https://buildwithlocus.com/deployment-workflows.md).
## Monorepo support
A project can contain multiple services from one repository. Set each service's `rootDir` to its source directory, such as `services/api` or `services/web`. One push deploys all services in the project.
## Project configuration (.locusbuild)
Keep service, addon, and variable configuration in a `.locusbuild` file at the repository root. Locus reads it during `from-repo` setup and git-push deploys.
See the [monorepo guide](https://buildwithlocus.com/monorepo.md) for the file format and [variables](/build/environment#full-stack-locusbuild-example) for a full-stack example.
## Troubleshooting
Start with the deployment logs. Common causes are a failing health endpoint, a port other than 8080, missing variables, or inaccessible source code.
A newly healthy deployment may take up to 60 seconds to serve traffic. For persistent failures, use the [troubleshooting guide](https://buildwithlocus.com/troubleshooting.md).
# x402 payments
Source: https://docs.paywithlocus.com/build/x402
Create and fund a Build workspace with USDC on Base or Polygon.
Use **USDC on Base or Polygon** to create a Build with Locus workspace and pay for deployment credits. An x402-compatible client handles the HTTP payment challenge, then receives a token for the Build API.
## How it works
1. Call the sign-up or top-up endpoint.
2. Read the HTTP `402` payment terms.
3. Authorize payment from your wallet and resend through your x402 client.
4. Receive a JWT and workspace details after settlement.
Your client handles the payment headers. Send your agent the [Build skill](https://buildwithlocus.com/SKILL.md) for the full request contract.
## Sign up via x402
```bash theme={null}
curl -sS -X POST https://api.buildwithlocus.com/v1/auth/x402-sign-up \
-H "Content-Type: application/json"
```
The first request returns `402`. After payment, the response includes `jwt`, `workspaceId`, and, for a new external wallet, `claimUrl`.
The JWT lasts **30 days**. Use it as a Bearer token for Build API requests. x402 workspaces receive **\$6.00** in initial credits.
## Top up credits via x402
Send the amount you want to add to the workspace:
```bash theme={null}
curl -sS -X POST https://api.buildwithlocus.com/v1/billing/x402-top-up \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"amount": 5.00}'
```
Your x402 client completes the payment challenge. Check `creditBalance` in the successful response. See [billing](https://buildwithlocus.com/billing.md) for credit management.
## Claim links
Open the returned `claimUrl` to connect your email and access the dashboard. Your agent can deploy with its JWT before the workspace is claimed.
## Git push deploys with x402
Use your JWT as the password in the Locus git remote:
```bash theme={null}
git remote add locus https://x:$JWT_TOKEN@git.buildwithlocus.com/{workspaceId}/{projectId}.git
git push locus main
```
Replace the workspace and project IDs with your own. Keep the credential-bearing remote private.
## MPP vs x402
Choose the protocol for the chain holding your funds:
| | MPP | x402 |
| --------------- | -------------- | -------------------------------- |
| Chain | Tempo (`4217`) | Base (`8453`) or Polygon (`137`) |
| Sign-up cost | \$0.001 USDC | Shown in the payment challenge |
| Initial credits | \$0.00 | \$6.00 |
Both create a Build workspace with the same deployment API. See [MPP payments](/build/mpp) for Tempo.
## Network details
| Network | USDC contract |
| ------- | -------------------------------------------- |
| Polygon | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` |
| Base | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
Payments settle through `https://facilitator.payai.network`. Compatible client libraries include `@x402/core` and `@x402/evm`.
# Buyer and agent guide
Source: https://docs.paywithlocus.com/checkout/for-buyers
Pay a Locus checkout with your wallet or send it to your agent.
Open a Locus checkout URL to pay with your Locus Wallet or an external wallet on Base. You can also send the URL to your agent and let it complete the payment within your spending limits.
## Paying with Locus Wallet
1. Click **Pay with Locus** and sign in if needed.
2. Review the amount and confirm payment.
3. Save the transaction hash from the confirmation screen.
Locus sponsors gas for this payment.
## Paying with an external wallet
Connect MetaMask, Coinbase Wallet, or another WalletConnect-compatible wallet. The checkout guides you through approving the USDC amount and signing the payment on Base.
Once the transaction confirms, Locus marks the session as paid. The [Payment Router](/checkout/payment-router) links the on-chain payment to your checkout session.
## Paying with an AI agent
Send your agent the checkout URL and your purchase instructions:
> Review this checkout link. Confirm the seller and amount with me, then pay from my Locus wallet and send me the receipt.
The page includes the information your agent needs to pay. Your agent submits the payment, checks confirmation, and reports the result.
### Setting up your agent with Locus
If your agent isn't connected, send it:
```text theme={null}
Read https://paywithlocus.com/skill.md and help me set up an Agent Platform wallet.
```
Follow the [quickstart](/quickstart) to create and fund the wallet. Your agent can use [checkout.md](https://paywithlocus.com/checkout.md) for payment instructions.
### Policy guardrails
Your dashboard controls apply to agent payments:
| Setting | Effect |
| ------------------------ | ----------------------------------------------------------------------------- |
| **Allowance** | Caps total spending. |
| **Max transaction size** | Caps one payment. |
| **Approval threshold** | Payments above the threshold need your approval. Your agent sends you a link. |
### Common scenarios
If funds are insufficient, add USDC to your wallet. If the checkout has expired, request a new link from the seller. Check your transaction history before retrying a payment with an uncertain result.
# Merchant integration
Source: https://docs.paywithlocus.com/checkout/for-merchants
Embed checkout, confirm payments, and track sales with the React SDK.
Create a checkout session on your server, then pass its ID to the React component. Your buyers get Locus Wallet, external wallet, and agent payment options in one integration.
For session creation and optional receipts, start with the [integration example](/checkout/integrate).
## Install
```bash title="Install the React SDK" theme={null}
npm install @withlocus/checkout-react
```
Requires React 17+.
## Embed checkout
```tsx CheckoutPage.tsx theme={null}
import { LocusCheckout } from '@withlocus/checkout-react';
function CheckoutPage({ sessionId }: { sessionId: string }) {
return (
{
console.log('Paid!', data.txHash);
// Show confirmation. Fulfill orders after server-side verification.
}}
onCancel={() => {
console.log('Buyer cancelled');
}}
onError={(error) => {
console.error('Checkout error:', error.message);
}}
/>
);
}
```
### Display modes
| Mode | What the buyer sees |
| -------------------- | ----------------------------------------------------------- |
| `embedded` (default) | Checkout inside your page. |
| `popup` | Checkout in a separate window. Closing it calls `onCancel`. |
| `redirect` | The hosted checkout page. |
Use `style` or `className` to style the component's wrapper. The SDK also exports `LOCUS_BRAND_COLORS`, `LOCUS_CTA_GRADIENT`, and `LOCUS_FONT_FAMILY` for surrounding UI.
### Payment callbacks
`onSuccess` receives `sessionId`, `amount`, `currency`, `txHash`, `payerAddress`, and `paidAt`. Use it to show confirmation.
Use `onCancel` for cancelled checkouts and `onError` to report failures.
Use callbacks to update the UI. [Verify payment on your server](#webhooks) before fulfilling an order.
## Webhooks
Set `webhookUrl` when creating the session. Locus sends a POST request when a payment confirms or a session expires:
| Event | Trigger |
| -------------------------- | ------------------------------- |
| `checkout.session.paid` | Payment confirmed on-chain |
| `checkout.session.expired` | Session expired without payment |
### Payload
```json title="Payment confirmation event" theme={null}
{
"event": "checkout.session.paid",
"data": {
"sessionId": "SESSION_ID",
"amount": "25.00",
"currency": "USDC",
"paymentTxHash": "0x...",
"payerAddress": "0x...",
"paidAt": "2026-03-01T12:00:00.000Z",
"metadata": { "userId": "usr_123", "plan": "pro" }
},
"timestamp": "2026-03-01T12:00:01.000Z"
}
```
### Signature verification
Verify `X-Signature-256` against the raw request body before fulfilling the order. Use the `whsec_` secret returned when you create a session with a webhook URL.
```typescript verify-webhook.ts theme={null}
import crypto from 'crypto';
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
const receivedBytes = Buffer.from(signature);
const expectedBytes = Buffer.from(expected);
return receivedBytes.length === expectedBytes.length &&
crypto.timingSafeEqual(receivedBytes, expectedBytes);
}
```
Reject requests with a missing or invalid signature. Match the paid session to your order, verify the amount, and fulfill it only once. The event name and session ID are also sent in `X-Webhook-Event` and `X-Session-Id`.
## Hook: `useLocusCheckout`
Use the hook for your own payment buttons:
```tsx PayButton.tsx theme={null}
import { useLocusCheckout } from '@withlocus/checkout-react';
function PayButton({ sessionId }: { sessionId: string }) {
const { openPopup, redirectToCheckout, getCheckoutUrl } = useLocusCheckout();
return (
);
}
```
## Merchant dashboard
The [dashboard](https://app.paywithlocus.com) tracks revenue, session count, conversion, and payment methods. Filter by time range or checkout instance, then open a session for payment details.
Use an instance ID to group sessions by integration point. Instances are created on first use. Buyers can find receipts in **Purchases**.
## API reference
Use [checkout.md](https://paywithlocus.com/checkout.md) for session APIs and agent payment requests. The [Payment Router](/checkout/payment-router) documents external wallet transactions.
# Checkout with Locus
Source: https://docs.paywithlocus.com/checkout/index
Accept USDC payments from people and agents with a drop-in checkout.
Add USDC payments to your app with a hosted checkout page and React component. Locus handles wallet connections, payment confirmation, and webhooks, so you can focus on what you're selling.
The same checkout works for people and AI agents. A person connects a wallet; an agent reads the checkout details and pays programmatically.
## Add checkout to your app
1. Create a session on your server with the amount, description, and optional receipt.
2. Show checkout inline, open a popup, or redirect to the hosted page.
3. Confirm payment through a signed webhook and fulfill the order.
Start with the [integration example](/checkout/integrate). The React SDK is `@withlocus/checkout-react`.
## Payment methods
| Method | Buyer experience |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| **Locus Wallet** | Sign in and confirm. Locus sponsors gas. |
| **External wallet** | Connect MetaMask, Coinbase Wallet, or another WalletConnect-compatible wallet and pay USDC on Base. |
| **AI agent** | Send the checkout URL to an agent connected to Locus. It can pay through the API. |
## Receipts and payment confirmation
Attach line items, tax, seller details, and support information to a session. The checkout page displays the receipt, and the buyer can find it later in **Purchases**.
When a payment is confirmed on-chain, Locus sends your server a webhook. The React component also calls `onSuccess` so your UI can show confirmation. [Verify the webhook signature](/checkout/for-merchants#webhooks) before fulfilling an order.
## Merchant dashboard
Track revenue, session conversion, and payment methods in the [dashboard](https://app.paywithlocus.com). Group sessions by checkout instance to compare different integration points.
## Sessions
Locus creates the session ID and checkout URL for you. Sessions expire after **30 minutes** by default.
| Status | Meaning |
| ------------- | ---------------------------- |
| **PENDING** | Awaiting payment |
| **PAID** | Payment confirmed on-chain |
| **EXPIRED** | Payment window ended |
| **CANCELLED** | Seller cancelled the session |
Only pending sessions can be modified.
## Next steps
Create a session and show checkout.
Configure the SDK and payment webhooks.
Pay with a wallet or your agent.
# Checkout integration example
Source: https://docs.paywithlocus.com/checkout/integrate
End-to-end examples for adding Locus Checkout to your app
Add checkout in two steps: create a session on your server and show it with the React component. Your API key stays server-side; the browser only needs a session ID.
Use the [merchant guide](/checkout/for-merchants#webhooks) to verify payment webhooks before fulfilling orders.
## Install
```bash title="Install the React SDK" theme={null}
npm install @withlocus/checkout-react
```
Requires React 17+.
## Create and show checkout
Call the Checkout API from your server with the price and order details. Keep the idempotency key stable for retries of this order; use a new key for each new purchase.
```typescript title="Server: create a session" theme={null}
const LOCUS_API_BASE_URL =
process.env.LOCUS_API_BASE_URL ?? 'https://api.paywithlocus.com/api';
if (!process.env.LOCUS_API_KEY) {
throw new Error('Missing LOCUS_API_KEY');
}
const response = await fetch(`${LOCUS_API_BASE_URL}/checkout/sessions`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
},
body: JSON.stringify({
amount: '25.00',
description: 'Pro plan - monthly',
successUrl: 'https://yourapp.com/success',
cancelUrl: 'https://yourapp.com/cancel',
webhookUrl: 'https://yourapp.com/api/webhooks/locus',
metadata: { orderId: 'order_123', userId: 'usr_123', plan: 'pro' },
idempotencyKey: 'checkout_order_123',
}),
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(payload.message ?? 'Failed to create checkout session');
}
const session = payload.data;
// session.id -> session ID (UUID)
// session.checkoutUrl -> hosted checkout URL
// session.expiresAt -> session expiration (default 30 min)
```
Pass the session ID to the `LocusCheckout` component on the client.
```tsx CheckoutPage.tsx theme={null}
import { LocusCheckout } from '@withlocus/checkout-react';
function CheckoutPage({ sessionId }: { sessionId: string }) {
return (
{
console.log('Payment confirmed:', data.txHash);
window.location.href = '/success';
}}
onCancel={() => {
console.log('Buyer cancelled');
window.location.href = '/cancel';
}}
onError={(error) => {
console.error('Checkout error:', error.message);
}}
/>
);
}
```
## With receipt
Add `receiptConfig` when creating the session to show line items, tax, and seller information. The same React component displays the receipt automatically.
```typescript title="Server: create a session with a receipt" theme={null}
if (!process.env.LOCUS_API_KEY) {
throw new Error('Missing LOCUS_API_KEY');
}
const response = await fetch('https://api.paywithlocus.com/api/checkout/sessions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
},
body: JSON.stringify({
amount: '27.50',
description: 'TechMart order #4821',
successUrl: 'https://yourapp.com/success',
cancelUrl: 'https://yourapp.com/cart',
webhookUrl: 'https://yourapp.com/api/webhooks/locus',
metadata: { orderId: 'order_4821' },
idempotencyKey: 'checkout_order_4821',
receiptConfig: {
enabled: true,
fields: {
creditorName: 'TechMart Inc.',
lineItems: [
{ description: 'Wireless Headphones', amount: '25.00' },
{ description: 'Shipping', amount: '0.00' },
],
subtotal: '25.00',
taxRate: '10%',
taxAmount: '2.50',
logoUrl: 'https://techmart.com/logo.png',
companyAddress: '123 Market St, San Francisco, CA 94105',
supportEmail: 'support@techmart.com',
},
},
}),
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(payload.message ?? 'Failed to create checkout session');
}
const session = payload.data;
// session.id -> pass to LocusCheckout on the client
```
### `receiptConfig` fields
| Field | Type | Description |
| ----------------------- | ------------------------------------------- | ---------------------------------------- |
| `enabled` | `boolean` | Enable the receipt on this session |
| `fields.creditorName` | `string` | Seller/company name shown on the receipt |
| `fields.lineItems` | `{ description: string, amount: string }[]` | Itemized charges |
| `fields.subtotal` | `string` | Subtotal before tax |
| `fields.taxRate` | `string` | Tax rate (e.g. `"10%"`) |
| `fields.taxAmount` | `string` | Tax amount in USDC |
| `fields.logoUrl` | `string` | URL to your company logo |
| `fields.companyAddress` | `string` | Company address |
| `fields.supportEmail` | `string` | Support email shown on receipt |
After payment, receipt details also appear in the buyer's **Purchases** tab on the Locus dashboard.
## Display modes
Set `mode` on `LocusCheckout` to choose the experience:
| Mode | Behavior |
| ---------- | ----------------------------------------------------- |
| `embedded` | Shows checkout inside your page. |
| `popup` | Opens a separate window; closing it calls `onCancel`. |
| `redirect` | Sends the buyer to the hosted checkout page. |
For custom buttons, use [`useLocusCheckout`](/checkout/for-merchants#hook-uselocuscheckout). It provides `openPopup`, `redirectToCheckout`, and `getCheckoutUrl`.
# Payment Router
Source: https://docs.paywithlocus.com/checkout/payment-router
Verify external wallet payments and their checkout sessions on Base.
The Payment Router transfers USDC from an external wallet to the seller and links the payment to a checkout session on-chain. Locus uses that link to confirm payment and notify the merchant.
The hosted checkout handles the contract interaction. Use this page when verifying a payment or building a custom wallet integration.
## How external wallet payments work
1. The buyer approves the router to spend the checkout's USDC amount.
2. The buyer calls `pay()` with the session ID, seller address, and amount.
3. The router transfers USDC and emits `CheckoutPayment`.
4. Locus marks the session as paid and sends the merchant a webhook.
## Contract addresses
| Contract | Base mainnet address (chain `8453`) |
| -------------- | -------------------------------------------- |
| Payment Router | `0x34184b7bCB4E6519C392467402DB8a853EF57806` |
| USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
The router is not deployed on Base Sepolia. USDC on Base Sepolia uses `0x036CbD53842c5426634e7929541eC2318f3dCF7e` (chain `84532`).
## Verify on BaseScan
Open the [Payment Router on BaseScan](https://basescan.org/address/0x34184b7bCB4E6519C392467402DB8a853EF57806).
* **Events** shows `CheckoutPayment` records with the session, buyer, seller, and amount.
* **Read Contract** lets you call `sessionPaid(bytes32)` to check a specific session.
* **Contract** contains the verified source and ABI for direct integrations.
## Contract interface
Use `pay(bytes32 sessionId, address recipient, uint256 amount)` for the standard payment flow. `payWithPermit` supports an EIP-2612 permit to combine approval and payment.
The contract exposes `sessionPaid(bytes32)` and `usdc()` for verification. Read the [verified contract](https://basescan.org/address/0x34184b7bCB4E6519C392467402DB8a853EF57806#code) for the complete interface.
### Session ID encoding
Remove the UUID's dashes, left-align its hex value, and zero-pad it to 32 bytes:
```text theme={null}
UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
bytes32: 0xa1b2c3d4e5f67890abcdef123456789000000000000000000000000000000000
```
### USDC amounts
USDC uses six decimals. A payment of **25.00 USDC** is `25000000` base units.
# Laso Finance
Source: https://docs.paywithlocus.com/features/laso
Let your agent buy online with a prepaid Visa card funded from USDC.
Laso Finance turns USDC from your Locus wallet into a prepaid virtual Visa card. Your agent can use it at supported online checkouts for purchases from **$5 to $1,000**.
Card ordering is **US-only**. Cards are non-reloadable, so confirm merchant compatibility and the total, including tax and shipping, before ordering.
## Make a purchase
> Check whether this merchant accepts Laso prepaid cards. If it does, get the final checkout total and ask me before ordering a card for that amount.
Your agent uses the [Laso guide](https://paywithlocus.com/laso.md) to check the merchant, order the card, and retrieve its number, CVV, and expiration. Cards are usually ready in about 7–10 seconds.
## Merchant compatibility
Laso keeps a record of previous card attempts. Your agent checks it before ordering:
| Status | What it means |
| ----------------------- | --------------------------------------------------------------- |
| **accepted** | A previous payment succeeded. |
| **not\_accepted** | A previous payment was declined. Choose another payment method. |
| **unknown** or unlisted | Acceptance is unconfirmed. |
Match the card amount to the checkout total; leftover funds stay on the non-reloadable card.
## Pricing
| Action | Cost |
| -------------------------------------- | -------------------------------------- |
| Authenticate | \$0.005 USDC |
| Order a card | $0.015 + card amount ($5–\$1,000 USDC) |
| Check card details, balance, or status | Free |
| Withdraw available account USDC | Free; \$0.01 minimum |
Paid actions are charged through Locus's x402 proxy. Your agent can reuse its session for free lookups and status checks.
## Spending controls
Your dashboard allowance, per-transaction limit, and approval threshold apply to paid Laso operations. See [agent settings](/platform-walkthrough#agent-settings).
## Agent reference
Send your agent [skill.md](https://paywithlocus.com/skill.md) to connect Locus and [laso.md](https://paywithlocus.com/laso.md) for card ordering, session management, balance checks, and withdrawals.
# USDC transfers
Source: https://docs.paywithlocus.com/features/send-types
Send USDC to wallet addresses or email recipients
Pay a contractor, reimburse a teammate, or move funds from your Locus wallet. Send USDC to a Base wallet address or an email recipient.
## Direct to address
Send USDC directly to any Base wallet address. The transfer is executed immediately on-chain.
## Direct to email
Send USDC to an email address. The recipient can choose a wallet when they claim the payment.
Locus holds the funds in a subwallet and emails the recipient a one-time password. [See how email claims work.](/features/wallets#subwallets)
Your agent's [spending limits](/platform-walkthrough#agent-settings) apply to both send types.
# Tasks
Source: https://docs.paywithlocus.com/features/tasks
Let your agent hire human taskers across popular platforms
Locus Tasks lets your agent hire people for graphic design, writing, and other work. Give it a brief, budget, and deadline; the finished work comes back to your agent and dashboard.
## How it works
Your agent chooses a task category (e.g., Graphic Design, Written Content) and a timeline: **1 day**, **3 days**, or **7 days**.
Each category + timeline pairing offers three price tiers based on available taskers:
| Tier | Expected Output |
| ------------ | --------------------------------- |
| Lower `(1)` | Budget-friendly, variable quality |
| Mid `(2)` | Balanced price and quality |
| Higher `(3)` | Premium quality work |
Include the deliverable, requirements, and reference links. Your agent submits the brief with your category, timeline, and price tier.
Our system matches your request with a human tasker based on category, timeline, and price.
We forward the request to the tasker and return the deliverable to your agent (also visible in your dashboard).
## Timing and refunds
**Deadlines**: We add a one-day grace period to account for processing delays or task start time.
* **No match found**: If we can't find a suitable tasker, you'll be refunded.
* **Price difference**: If the tasker's total charge is less than your agent's price tier, we refund the difference.
# Wallets
Source: https://docs.paywithlocus.com/features/wallets
Give your agent a USDC balance while keeping control of its wallet.
A Locus wallet lets your agent pay for tools, send USDC, and make purchases from one balance on Base. Locus sponsors gas, so you don't need to keep ETH in the wallet for these transactions.
You retain a recovery key and can revoke Locus's signing access. Set an allowance and approval threshold in the [dashboard](/platform-walkthrough#agent-settings) to control your agent's spending.
## Your keys
### User key
You control this key. Use it to recover the wallet or revoke Locus's permissioned key. It is generated in your browser and never stored on Locus servers.
Save your user key securely when you create the wallet. See the [quickstart](/quickstart) for setup.
### Permissioned key
Locus stores this key in a hardware security module to sign agent transactions. It can rotate itself; only your user key can fully revoke it.
## Subwallets
Email payments use subwallets to hold funds until the recipient claims them:
1. Send USDC to an email address.
2. Locus places the funds in a separate subwallet.
3. The recipient receives an email with a one-time password.
4. They claim the funds to a wallet address of their choosing.
Each payment has a claim deadline. Funds cannot be disbursed after that deadline. Claimed subwallets return to a reuse pool for future payments.
See [USDC transfers](/features/send-types) for the two ways to send funds.
## Locus smart wallet
Locus wallets use [ERC-4337](https://docs.erc4337.io/index.html) accounts based on [Solady](https://github.com/Vectorized/solady). Either the user key or active permissioned key can sign. The user key can call `revokePermissionedKey()` to remove Locus's access.
The wallet implementation is immutable: `_authorizeUpgrade` always reverts.
## Factory
`LocusFactory` deploys wallets at deterministic addresses using CREATE2. The permissioned key is set during deployment.
For contract methods and subwallet limits, inspect the verified implementations:
Signing, access revocation, transfers, and wallet deployment.
Email payment escrow, deadlines, and claims.
# Account setup and sign-in
Source: https://docs.paywithlocus.com/locus-pro/account-setup
Join your enterprise workspace, sign in, and manage account security.
Join an enterprise workspace through an evaluation or team invitation. One Locus identity can access multiple workspaces; choose the active workspace after signing in.
For a self-serve account, start with the [Locus Pro quickstart](/locus-pro/individual/quickstart).
## Accept an invitation
Follow the single-use link in your invitation email.
Sign in or create the invited identity.
Choose the workspace and review your assigned role.
An **evaluation invitation** creates the workspace and promotional balance described in the invitation. A **team invitation** adds you to an existing workspace as an admin, developer, billing member, or viewer.
Team invitations expire after seven days. Ask a workspace owner or admin to resend an expired or revoked invitation.
## Sign in
Use your password, passkey, or an available linked provider. Locus supports Google, GitHub, GitLab, and Ethereum when configured.
Manage linked methods from **Account security**. Link an Ethereum wallet there before using it to sign in. Wallet authentication requests a message signature and does not authorize a transaction or access to funds.
Accounts with SMS or TOTP multi-factor authentication must use a password
or passkey to complete sign-in.
## Secure your workspace
Use separate logins for team members and assign the access each person needs. Owners and admins complete MFA or passkey verification for sensitive changes such as key creation and membership changes.
Disconnecting a sign-in method stops future sign-ins through that method. To revoke existing account sessions, change your password.
## Create a self-serve account
[Sign up](https://platform.paywithlocus.com/signup) with an available method. Email signup uses a six-digit verification code. Ethereum signup also verifies a recovery email.
Your account starts with a zero prepaid balance. You can connect an agent before funding it; add credits before paid tool use. If confirmation succeeds but setup is interrupted, sign in and select **Finish account setup**.
A self-serve account and an enterprise workspace can share the same sign-in identity. Creating or funding an account does not create an enterprise agreement.
Fund the workspace, enable a tool, and make your first call.
Choose credentials and team access.
# Activity and analytics
Source: https://docs.paywithlocus.com/locus-pro/activity-and-analytics
See what your agents spend, investigate individual charges, and track customer usage and margin.
See which users and agents drive spend, which tools they call, and how much margin your product earns.
| Open | To answer |
| ------------- | -------------------------------------------- |
| **Activity** | Who spent the credits, on which tools? |
| **Analytics** | How are usage and margin changing over time? |
Both views use UTC and report completed tool charges.
## Investigate spend in Activity
Filter by spender, provider, endpoint, and period. You can focus on a workspace member, end user, Agent Connection, or API credential.
Activity shows:
* **Gross spend** and completed tool calls.
* **Average charge per call** and active spenders.
* Spend over time, provider breakdowns, and transaction history.
* The current **pool balance**.
For example, select an end user and an enrichment provider to see what that customer's agent spent this month. The filters appear in the URL, so you can bookmark the view or share it with another authorized workspace member.
Transaction-type and attribution filters narrow the transaction list.
They do not change the analytics totals above it.
## Track trends in Analytics
Choose 7, 30, or 90 days to compare with the preceding period. Analytics shows usage, call volume, average charge, gross margin, active end users, and your top services and spenders.
Use it to answer questions such as:
* Which customer features account for the most provider spend?
* Is usage growing faster than margin?
* Which tools and users should we investigate in Activity?
Gross spend is measured before refunds. For top-ups, allocations, refunds, and other balance movements, use the transaction ledger.
## Query the same data from your server
A tenant secret key with `tenant:read` can read:
| Endpoint | Use it for |
| --------------------------------- | ---------------------------------------------------- |
| `GET /api/credits/analytics` | Usage totals, comparisons, time series, and rankings |
| `GET /api/credits/ledger` | Individual balance movements and attribution |
| `GET /api/credits/ledger/summary` | Counts and amounts by transaction category |
These endpoints support filters for time, provider, endpoint, and spender. The ledger also supports your attribution fields. See the [API reference](/api-reference/introduction) for filter names, pagination, and response schemas.
## Locus Pro usage
Self-serve accounts have a simpler **Usage** page with tool spend, completed calls, and top tools over 7, 30, or 90 days. Card top-ups appear separately under **Credits → Payment history**. See [Locus Pro account and usage](/locus-pro/individual/account-and-usage) for details.
Understand how balances, customer payments, and margin connect.
Build reports from analytics and ledger data.
# Agent-native onboarding
Source: https://docs.paywithlocus.com/locus-pro/agent-native-onboarding
Let an agent create its own Locus account, request funding, and connect to paid tools.
An agent can set up Locus Pro without a dashboard login or workspace invitation. It verifies its identity through AgentID, asks a person to fund its balance through Stripe Checkout, and connects to tools through MCP.
The account starts at **\$0**. The agent can manage its own tools, balance, and credentials. The payer's card stays in Checkout.
## Let the agent handle setup
Give your agent the [Locus skill](https://paywithlocus.com/SKILL.md) and this prompt:
```text title="Send to your agent" wrap theme={null}
Create a Locus Pro account for yourself through AgentID. Set up the tools you
need for web research, then send me a funding link. Connect through MCP once
the balance is ready.
```
The agent starts by reading the current onboarding instructions:
```bash title="Read onboarding instructions" theme={null}
curl --fail-with-body https://api.paywithlocus.com/api/credits/agent/onboarding
```
This public endpoint returns the flow and URLs the agent needs.
## How setup works
The agent generates a recovery token and begins registration. It follows
the returned AgentID authorization URL to verify its identity and inbox.
The agent repeats the original registration request after approval.
It stores the returned account credential and recovery token securely.
The agent adds the hosted MCP server and completes OAuth using the same
AgentID identity.
The agent enables the tools it needs and creates a Stripe Checkout link
for a specific amount. You review and pay through that link.
The agent waits for funding status to become `ready`, then uses its MCP
connection to discover and call tools.
## What the payer approves
| Funding link | What it means |
| ------------------- | ------------------------------------------------------ |
| One amount | You approve only that payment, not future card charges |
| One-hour expiry | The agent needs a new link after it expires |
| Agent-owned account | Paying does not transfer account ownership to you |
Share only the funding link. Never paste card details into chat.
## Building your own onboarding flow
The [API reference](/api-reference/introduction) defines the requests and responses. The [AgentID authentication reference](https://paywithlocus.com/agent/auth.md) covers browserless identity verification.
### Registration and recovery
Generate 24 random bytes encoded as unpadded base64url:
```javascript title="Generate a recovery token" theme={null}
import { randomBytes } from "node:crypto";
const registrationToken = randomBytes(24).toString("base64url");
```
Send it with an account name to `POST /api/credits/agent/register`. A `202` response includes `account.registration.authorizationUrl`. Complete that authorization, then replay the exact name and token before the pending registration expires.
Save `account.connection.credential` from the activation response. This `lcac_…` credential authorizes the agent-account REST routes; tool access uses MCP OAuth.
### MCP connection
```text title="MCP server URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp
```
Choose AgentID during authorization and use the identity that registered the account. On a headless host, keep the client's login process and callback listener running throughout the handoff.
### Tool access and funding
| Operation | Route |
| -------------------------------- | ------------------------------------------ |
| Read account and balance | `GET /api/credits/agent/account` |
| Find tools | `POST /api/credits/agent/catalog/search` |
| Enable an ordinary provider tool | `PUT /api/credits/agent/catalog` |
| Read funding limits | `GET /api/credits/agent/funding/config` |
| Create a funding link | `POST /api/credits/agent/funding-sessions` |
Use a stable `Idempotency-Key` when retrying a funding request. Poll the returned `statusUrl` at the suggested interval and continue only when its state is `ready`.
## Rotate the credential
Use `POST /api/credits/agent/credential/rotate` with the current credential and a newly generated recovery token. Save the new credential and token together; rotation replaces both immediately.
Keep both secrets out of funding messages, prompts, and source repositories.
# Authentication and scopes
Source: https://docs.paywithlocus.com/locus-pro/authentication-and-scopes
Choose credentials for servers, agents, and browsers, then limit what each can access.
Give each integration the access it needs. Keep tenant secret keys on trusted servers, use scoped Agent Connections for unattended agents, and connect interactive MCP clients through OAuth.
The keys and workspace roles on this page are Locus Pro Enterprise features. For self-serve setup, see [Connect your agent](/locus-pro/individual/connect-agents).
## Choose a credential
| Credential | Use it for |
| ------------------------------- | ------------------------------------------------------------------------------- |
| **Dashboard session** | Human administration, limited by workspace role |
| **Tenant secret key** (`lcr_…`) | Trusted-server calls and scoped management API access |
| **Publishable key** (`lcrpk_…`) | Browser/widget pairing; it cannot authorize calls by itself |
| **End-user token** | Calls and balance access for one customer |
| **Agent Connection** (`lcac_…`) | An unattended agent with an expiry, allowed tools, and optional spending limits |
| **Sandbox key** (`lcrsb_…`) | Simulated direct calls with no provider requests or credit charges |
An Agent Connection keeps an agent tied to its assigned account and limits. Use it when the credential will live inside an agent runtime. Use a [sandbox key](/locus-pro/sandbox) for integration tests.
## Issue and revoke safely
Sign in as a workspace owner or admin and complete MFA or passkey verification.
Open **API Keys** and choose the scopes your integration needs.
Save the raw value in your server's secret manager. Locus shows it only once.
Check access and test the integration before retiring the old credential.
You can rotate a key with a grace period so the old and new values overlap during deployment. Revoke credentials that are no longer in use and review the credential audit in the dashboard.
Never put a tenant secret key in browser code, a mobile app, a prompt, or a
source repository. For customer-facing browser features, issue a short-lived
end-user token on your server.
## Enterprise management scopes
| Scope | Access |
| -------------------- | ------------------------------------------------------------- |
| `tenant:read` | Workspace, catalog, balance, usage, ledger, and billing reads |
| `tenant:write` | Workspace settings and webhook replay |
| `catalog:write` | Tool enablement and pricing |
| `credits:move` | Credit allocation, top-ups, and secret-key metered calls |
| `credentials:manage` | Key, Agent Connection, and webhook-secret lifecycle |
| `tokens:manage` | End-user policies and token lifecycle |
| `payouts:manage` | Auto-recharge and payout settings |
| `members:manage` | Workspace membership |
| `widget:read` | Reserved scope attached to publishable keys |
Scopes do not override workspace roles. Sensitive changes, including API-key lifecycle, membership, spend controls, and payout settings, require a workspace owner or admin with recent MFA or passkey verification. An API key cannot satisfy that requirement. Custom API changes remain owner-only.
### Automating Agent Connections
A server key with both `credentials:manage` and `credits:move` can create or rotate Agent Connections without human verification. Revocation needs only `credentials:manage`. Dashboard callers need an owner or admin role and recent verification.
## Enterprise workspace roles and invitations
| Role | Typical access |
| ------------- | --------------------------------------------------------------------------------- |
| **Owner** | Full workspace administration, including Custom API changes |
| **Admin** | Team, keys, billing, spending controls, catalog, and integrations |
| **Developer** | Catalog configuration and pricing; inspect Agent Connections and integration data |
| **Billing** | Billing and usage reads; funding changes require an owner or admin |
| **Viewer** | Read-only balances, usage, analytics, and membership |
Custom API changes are restricted to the owner. The original owner cannot be removed or reassigned.
An owner or admin can invite members from **Team**. Assign one non-owner role to each invitee. Invitations expire after seven days; an owner or admin can resend or revoke them. Membership changes require recent MFA or passkey verification.
## Check access
Use the credential endpoint to see the current credential's scopes and role:
```bash theme={null}
curl --fail-with-body \
https://api.paywithlocus.com/api/credits/auth/credential \
-H "Authorization: Bearer $LOCUS_SECRET_KEY"
```
The response contains authorization metadata, never the raw secret. Dashboard sessions with multiple workspace memberships must also identify the active workspace with `X-Locus-Tenant-Id`.
## Handle authorization errors
| Response | What to do |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `401` | Check the credential type, expiry, and revocation status |
| `403 INSUFFICIENT_SCOPE` | Use a credential with the required scope |
| `STEP_UP_REQUIRED` | Have an owner or admin complete MFA or passkey verification; Custom API changes require the owner |
Repeating the same request does not resolve missing access. The [API reference](/api-reference/introduction) lists each route's requirements. See [Account setup](/locus-pro/account-setup) for sign-in methods.
# Recipe routing
Source: https://docs.paywithlocus.com/locus-pro/capability-routing
Preview and run multi-provider search and flight Recipes from your server.
Use a routed Recipe when your application needs results across providers through one request. Locus selects eligible providers, merges their results, and returns sources and a billing receipt.
For the full set of outcomes and use cases, start with [Recipes](/locus-pro/enterprise/recipes). This page covers server-side search and flight routing.
## Choose an endpoint
| Slug | Result |
| ---------------------------- | ------------------------------------------------------------------------- |
| `router/web-search` | Ranked, deduplicated search results with provider sources |
| `router/web-research` | Research using a suitable structured source or multi-provider search |
| `locus-travel/flight-search` | Normalized flight options with source confidence and booking availability |
Costs vary with the providers used. These routes charge for successful underlying calls; preview requests are free.
## Configure the eligible pool
Open **Agent tools → Multi-Provider Web Search** to set the provider allowlist, search breadth, and result limit. Providers must also have an enabled catalog access path.
| Mode | Search breadth |
| --------------- | -------------------------------------------- |
| `fast` | Up to two eligible engines |
| `balanced` | Up to the selected provider limit; default 4 |
| `comprehensive` | Every eligible engine |
Your allowlist is a hard boundary. A request can narrow it further but cannot add providers outside it.
## Preview without calling providers
Append `/preview` to the execution route to see the planned providers and estimated charge:
```bash theme={null}
curl --fail-with-body -X POST \
"https://api.paywithlocus.com/api/wrapped/credits/router/web-search/preview" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "recent primary-source announcements about coding agents",
"mode": "balanced",
"maxResults": 10
}'
```
A preview spends no credits. Availability and prices can change before execution, so pass `maxCredits` to set an execution-time ceiling.
## Run a routed search
```bash theme={null}
curl --fail-with-body -X POST \
"https://api.paywithlocus.com/api/wrapped/credits/router/web-search" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Idempotency-Key: research-coding-agents-1" \
-H "Content-Type: application/json" \
-d '{
"query": "recent primary-source announcements about coding agents",
"mode": "balanced",
"maxResults": 10,
"maxCredits": "500"
}'
```
The main controls are search mode, result count, recency, country, domains, and the credit ceiling. If the estimated charge exceeds `maxCredits`, Locus rejects the plan before dispatch without charging.
Reuse the idempotency key when retrying the same logical request. Use a new key for a new request.
## Read the result and receipt
The response includes results, provider outcomes, and `billing.chargedCredits`. A `partial: true` response means some providers failed while others produced results. Review those results before requesting more work; successful calls can still be charged.
Agents discover these routes through their normal tool search. Connection allowlists and spending limits continue to apply.
## Compare flights with Locus Travel
Call `locus-travel/flight-search/preview` with airports, dates, and preferences. Execute the same body at `locus-travel/flight-search` with an idempotency key.
```json theme={null}
{
"origin": "SFO",
"destination": "JFK",
"departureDate": "2026-10-15",
"adults": 1,
"cabinClass": "economy",
"maxStops": 1,
"maxResults": 5,
"maxCredits": "500"
}
```
Results include itineraries, provider sources, warnings, booking availability, and the exact charge. If the route returns `202`, retry the same request with the same idempotency key to collect the result.
See the [API reference](/api-reference/introduction) for all filters, response fields, and workspace routing settings.
# Tools and the catalog
Source: https://docs.paywithlocus.com/locus-pro/catalog
Choose the APIs your agents can use, set customer pricing, and discover tools at runtime.
Give your agents access to search, scraping, enrichment, market data, inference, media, and more through one catalog. Enable the tools your product needs; Locus handles provider access and per-call billing.
Open **Agent tools** in your enterprise workspace to browse tools, see prices, and manage access. Self-serve accounts use **Tools**.
## Find the right tool
Search by the task or provider in **Agent tools**.
Check its inputs, price, and availability.
Enable the endpoints your agent needs. Ordinary provider endpoints start
disabled; some built-in Recipes are system-managed.
Use a direct tool when a specific provider, dataset, or operation matters. Use a [Recipe](/locus-pro/enterprise/recipes) when you want a complete outcome such as an enriched record or a cited research answer.
The directory snapshot covers **3,811 services** and **15,977 endpoints**. Availability and prices can change, so use your workspace's live catalog when configuring an integration.
Browse the full catalog by provider.
Browse Parse services by category.
## Control access and pricing
Enable an endpoint or a whole provider. For customer-billed calls, set a percentage markup, a flat markup, or both. Pricing falls back from endpoint settings to provider settings to your workspace default.
For example, enable a search tool and add a 25% markup:
```bash theme={null}
curl --fail-with-body -X PUT "https://api.paywithlocus.com/api/credits/catalog/tavily/search" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":true,"markupBps":2500}'
```
Pooled calls charge your workspace the base price. Markup applies when the call charges an end-user balance. See [Credits and pricing](/locus-pro/credits-and-pricing) for examples.
Execution requires a tool to be enabled, currently available, and permitted by the calling credential. The agent can inspect access through its connection before making a call.
## Read the live catalog
Use a tenant secret key to get the workspace's current providers, endpoints, enablement, and effective prices:
```bash theme={null}
curl --fail-with-body "https://api.paywithlocus.com/api/credits/catalog" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY"
```
The response includes each endpoint's slug, availability, and pricing. Dynamic prices depend on request inputs, measured usage, or an external quote.
For management interfaces, use `POST /api/credits/catalog/search` to find entries including disabled tools. For agent execution, use `POST /api/credits/tools/search` or MCP discovery.
## Show customers their tools
Use `GET /api/credits/me/catalog` with an end-user token to show that customer's available tools and final prices. It applies workspace enablement and the user's access policy while keeping your base cost and margin private.
This is useful when your app lets customers browse available capabilities before spending credits. The [API reference](/api-reference/introduction) covers filtering, pagination, and response fields.
## Understand variable prices
### Response-priced endpoints
Some tools reserve a maximum before execution, then settle against measured usage and release the unused amount. Your markup applies to the measured base. See [response-priced endpoints](/locus-pro/credits-and-pricing#response-priced-endpoints).
### Live-quoted endpoints
Some external services show **Priced live per call**. Their price comes from the service at execution time. Ask the agent to inspect the current quote and set a hard `max_charge_credits` ceiling before running them.
For x402 services, MCP `estimate_cost` supports a no-payment quote with `preflight_external_quote: true`. If a quote exceeds the execution ceiling, Locus declines the call without charging.
Agents discover the current request format through each endpoint's schema. See the [API reference](/api-reference/introduction) for direct-call formats.
## Give an agent workspace-specific docs
Locus generates Markdown for the tools your workspace has enabled:
```bash theme={null}
curl --fail-with-body "https://api.paywithlocus.com/api/credits/md?provider=tavily" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY"
```
Omit `provider` for the enabled catalog index. These authenticated docs include base costs and markup, so keep them in trusted server workflows. Never expose your secret key to an agent runtime or end user.
## Add your own service
[Custom APIs](/locus-pro/custom-apis) bring your HTTP services into the same discovery and access controls. Account integrations such as Gmail or Slack OAuth connections remain with your existing integration platform.
Let agents discover and call your enabled tools.
Set a default markup and override it where needed.
# API directory
Source: https://docs.paywithlocus.com/locus-pro/catalog-directory
Find APIs for AI, research, enrichment, finance, and more.
Browse APIs your agent can use through one Locus balance. Find a provider below,
or ask your agent to search for the task you want to complete.
Enable tools in the [dashboard](https://platform.paywithlocus.com). Check their
current price and availability before calling them. This directory is a
September 2026 snapshot with **3,811 catalog services** and **15,977 callable endpoints**.
* **50 Locus and partner providers** expose 295 direct endpoints.
* **3,284 callable Parse namespaces** expose 15,204 direct endpoints across 24 categories. The directory retains 3,290 listings, including six without callable endpoints.
* **475 MPP and x402 services** expose one live-quoted endpoint each.
* **2 system-managed services** expose 3 capability routes.
Use the dashboard's source filter to browse Locus, partner, Parse, MPP, or x402
services. Prices below exclude any markup set by an enterprise workspace.
New to Locus? Start with the [quickstart](/locus-pro/individual/quickstart) or
the [Enterprise quickstart](/locus-pro/enterprise/quickstart).
## Locus and partner providers
### AI & LLMs
| Provider | Endpoint | Slug | Base price |
| ------------- | ----------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
| Anthropic | Messages | `anthropic/chat` | Model-dependent (\~\$0.001–\$0.20) |
| Anthropic | Count Tokens | `anthropic/count-tokens` | \$0.001 |
| Anthropic | List Models | `anthropic/models` | \$0.001 |
| Deepgram | Transcribe Audio | `deepgram/transcribe` | \$0.05 + \$0.003 fee |
| Deepgram | Text to Speech | `deepgram/speak` | \$0.02 + \$0.003 fee |
| Deepgram | Flux Text to Speech | `deepgram/speak-flux` | \~\$0.045 per 1,000 characters + \$0.003 fee |
| Deepgram | Analyze Text | `deepgram/analyze` | \$0.01 + \$0.003 fee |
| Deepgram | List Models | `deepgram/list-models` | \$0.001 + \$0.003 fee |
| DeepL | Translate | `deepl/translate` | \$0.025+ (scales with text length) |
| DeepL | Rephrase (Write) | `deepl/rephrase` | \$0.025+ (scales with text length) |
| DeepL | Languages | `deepl/languages` | \$0.005 fee only |
| DeepSeek | Chat | `deepseek/chat` | Usage-based; the 402 challenge advertises the authorization maximum |
| DeepSeek | Fill-In-the-Middle (FIM) | `deepseek/fim` | Usage-based; the 402 challenge advertises the authorization maximum |
| DeepSeek | List Models | `deepseek/list-models` | \$0.003 fee only |
| Diffbot NL | Analyze Text | `diffbot-nl/analyze` | \$0.004+ (per 10k chars) |
| ElevenLabs | Text to Speech | `elevenlabs/tts` | \$0.05/1K chars (Turbo/Flash) or \$0.10/1K chars (Multilingual) + \$0.003 |
| fal.ai | Generate | `fal/generate` | \$0.006–\$10+ depending on model, duration, resolution, and audio |
| fal.ai | Status | `fal/status` | \$0.003 |
| fal.ai | Result | `fal/result` | \$0.003 |
| Google Gemini | Chat | `gemini/chat` | Model-dependent (\~\$0.003–\$0.15) |
| Google Gemini | Upload Video File | `gemini/upload-file` | \$0.003 |
| Google Gemini | Embed | `gemini/embed` | \~\$0.0002 |
| Google Gemini | Count Tokens | `gemini/count-tokens` | \$0.001 |
| Google Gemini | List Models | `gemini/models` | \$0.001 |
| Grok | Chat Completions | `grok/chat` | Usage-based; the 402 challenge advertises the authorization maximum |
| Grok | Image Generation | `grok/image-generate` | \$0.02–\$0.08 per image |
| Grok | Image Editing | `grok/image-edit` | \$0.02–\$0.08 per image |
| Grok | Chat with Web Search | `grok/web-search` | Usage-based; the 402 challenge advertises the authorization maximum |
| Grok | Chat with X Search | `grok/x-search` | Usage-based; the 402 challenge advertises the authorization maximum |
| Grok | Chat with Code Execution | `grok/code-execution` | Usage-based; the 402 challenge advertises the authorization maximum |
| Grok | Text-to-Speech | `grok/tts` | \~\$0.005 per 1,000 characters |
| Grok | List Models | `grok/models` | \$0.001 |
| Groq | Chat Completion | `groq/chat` | \$0.005 – \$0.10 (varies by model and tokens) |
| Groq | List Models | `groq/models` | \$0.005 fee only |
| Mathpix | Process Image | `mathpix/process-image` | \$0.005 |
| Mathpix | Process Strokes | `mathpix/process-strokes` | \$0.013 |
| Mistral AI | Chat Completion | `mistral/chat` | Usage-based; the 402 challenge advertises the authorization maximum |
| Mistral AI | Embeddings | `mistral/embed` | \$0.008 |
| Mistral AI | Moderation | `mistral/moderate` | \$0.008 |
| Mistral AI | List Models | `mistral/models` | \$0.005 fee only |
| OpenAI | Chat Completions | `openai/chat` | Model-dependent (\~\$0.001–\$0.20) |
| OpenAI | Embeddings | `openai/embed` | \~\$0.0001–\$0.001 |
| OpenAI | Image Generation | `openai/image-generate` | \$0.006–\$0.22 per image |
| OpenAI | Text-to-Speech | `openai/tts` | \~\$0.015 per 1K chars |
| OpenAI | Moderation | `openai/moderate` | \$0.001 |
| OpenAI | List Models | `openai/models` | \$0.001 |
| OpenRouter | Chat Completions | `openrouter/chat` | Model-dependent (\~\$0.001–\$0.50) |
| Origami | Research | `origami/research` | \$0.018 per settled credit (authorization maximum set by maxCredits) |
| Perplexity | Sonar Chat | `perplexity/chat` | Usage-based; the 402 challenge advertises the authorization maximum |
| Perplexity | Web Search | `perplexity/search` | Metered; currently \$0.00575 |
| Perplexity | Embeddings | `perplexity/embed` | Usage-based; the 402 challenge advertises the authorization maximum |
| Perplexity | Contextualized Embeddings | `perplexity/context-embed` | Usage-based; the 402 challenge advertises the authorization maximum |
| Ramp Router | List Models | `ramp-router/models` | \$0.001 |
| Ramp Router | Create Response | `ramp-router/responses` | Usage-based; request budget sets the authorization maximum |
| Ramp Router | Chat Completion | `ramp-router/chat` | Usage-based; request budget sets the authorization maximum |
| Replicate | Run Model | `replicate/run` | Model-dependent (\$0.005–\$0.05) |
| Replicate | Get Prediction | `replicate/get-prediction` | \$0.003 |
| Replicate | Get Model | `replicate/get-model` | \$0.001 + \$0.003 fee |
| Replicate | List Models | `replicate/list-models` | \$0.001 + \$0.003 fee |
| Stability AI | Generate Ultra | `stability-ai/generate-ultra` | \$0.092 |
| Stability AI | Generate Core | `stability-ai/generate-core` | \$0.034 |
| Stability AI | Generate SD3 | `stability-ai/generate-sd3` | \$0.029–\$0.075 (model-dependent) |
| Stability AI | Erase | `stability-ai/erase` | \$0.057 |
| Stability AI | Inpaint | `stability-ai/inpaint` | \$0.057 |
| Stability AI | Outpaint | `stability-ai/outpaint` | \$0.046 |
| Stability AI | Search and Replace | `stability-ai/search-and-replace` | \$0.057 |
| Stability AI | Search and Recolor | `stability-ai/search-and-recolor` | \$0.057 |
| Stability AI | Remove Background | `stability-ai/remove-background` | \$0.057 |
| Stability AI | Replace Background & Relight | `stability-ai/replace-background-and-relight` | \$0.092 |
| Stability AI | Upscale Fast | `stability-ai/upscale-fast` | \$0.023 |
| Stability AI | Upscale Conservative | `stability-ai/upscale-conservative` | \$0.46 |
| Stability AI | Upscale Creative | `stability-ai/upscale-creative` | \$0.69 |
| Stability AI | Sketch | `stability-ai/sketch` | \$0.057 |
| Stability AI | Structure | `stability-ai/structure` | \$0.057 |
| Stability AI | Style Guide | `stability-ai/style-guide` | \$0.057 |
| Stability AI | Style Transfer | `stability-ai/style-transfer` | \$0.092 |
| Stability AI | Stable Fast 3D | `stability-ai/stable-fast-3d` | \$0.115 |
| Stability AI | Stable Point Aware 3D | `stability-ai/stable-point-aware-3d` | \$0.046 |
| Stability AI | Text to Audio | `stability-ai/text-to-audio` | \$0.23 (50 steps, stable-audio-2) |
| Stability AI | Audio to Audio | `stability-ai/audio-to-audio` | \$0.23 (50 steps, stable-audio-2) |
| Stability AI | Audio Inpaint | `stability-ai/audio-inpaint` | \$0.23 (50 steps, stable-audio-2) |
| Stability AI | Stable Audio 3 Text to Audio | `stability-ai/text-to-audio-3` | \$0.299 |
| Stability AI | Stable Audio 3 Audio to Audio | `stability-ai/audio-to-audio-3` | \$0.299 |
| Stability AI | Stable Audio 3 Inpaint | `stability-ai/audio-inpaint-3` | \$0.299 |
| Stability AI | Result | `stability-ai/result` | \$0.001 |
| Suno | Generate Music | `suno/generate-music` | \$0.10 + \$0.005 fee |
| Suno | Get Music Status | `suno/get-music-status` | \$0.005 fee only |
| Suno | Generate Lyrics | `suno/generate-lyrics` | \$0.02 + \$0.005 fee |
| Suno | Get Lyrics Status | `suno/get-lyrics-status` | \$0.005 fee only |
### Search & Scraping
| Provider | Endpoint | Slug | Base price |
| ------------ | --------------------------- | -------------------------------- | ------------------------------------------------------------------ |
| Brave Search | Web Search | `brave/web-search` | \$0.035 |
| Brave Search | News Search | `brave/news-search` | \$0.035 |
| Brave Search | Image Search | `brave/image-search` | \$0.035 |
| Brave Search | Video Search | `brave/video-search` | \$0.035 |
| Brave Search | LLM Context | `brave/llm-context` | \$0.035 |
| Brave Search | AI Answers | `brave/answers` | \$0.085 |
| Browser Use | Run Task | `browser-use/run-task` | \$0.01+ |
| Browser Use | Get Task | `browser-use/get-task` | \$0.003 |
| Browser Use | Get Task Status | `browser-use/get-task-status` | \$0.003 |
| Browser Use | Stop Task | `browser-use/stop-task` | \$0.003 |
| DataForSEO | Google SERP (Live Advanced) | `dataforseo/serp-google-organic` | \$0.005/task (10 results) |
| DataForSEO | Search Volume (Google Ads) | `dataforseo/search-volume` | \$0.093/task (up to 1,000 keywords) |
| Diffbot | Article | `diffbot/article` | \$0.0042 |
| Diffbot | Product | `diffbot/product` | \$0.0042 |
| Diffbot | Discussion | `diffbot/discussion` | \$0.0042 |
| Diffbot | Image | `diffbot/image` | \$0.0042 |
| Diffbot | Video | `diffbot/video` | \$0.0042 |
| Diffbot | Analyze | `diffbot/analyze` | \$0.0042 |
| Diffbot | Event | `diffbot/event` | \$0.0042 |
| Diffbot | List | `diffbot/list` | \$0.0042 |
| Diffbot | Job Posting | `diffbot/job` | \$0.0042 |
| Exa | Search | `exa/search` | \$0.01 |
| Exa | Contents | `exa/contents` | \$0.004/page |
| Exa | Find Similar | `exa/find-similar` | \$0.01 |
| Exa | Answer | `exa/answer` | \$0.008 |
| Firecrawl | Scrape | `firecrawl/scrape` | \$0.003+ |
| Firecrawl | Crawl | `firecrawl/crawl` | \$0.01+ |
| Firecrawl | Crawl Status | `firecrawl/crawl-status` | \$0.003 |
| Firecrawl | Map | `firecrawl/map` | \$0.00383 |
| Firecrawl | Extract | `firecrawl/extract` | \$0.007+ |
| Firecrawl | Extract Status | `firecrawl/extract-status` | \$0.003 |
| Firecrawl | Batch Scrape | `firecrawl/batch-scrape` | \$0.003+/url |
| Firecrawl | Batch Scrape Status | `firecrawl/batch-scrape-status` | \$0.003 |
| Firecrawl | Search | `firecrawl/search` | \$0.00466 |
| Parallel | Search | `parallel/search` | \$0.004 (turbo) / \$0.008 (default) + \$0.001 per result beyond 10 |
| Parallel | Extract | `parallel/extract` | \$0.004 (1 URL) + \$0.001 per additional URL |
| Parallel | Responses | `parallel/responses` | \$0.013 (low) / \$0.053 (medium, default) / \$0.253 (high) |
| Tavily | Search | `tavily/search` | \$0.09 (basic) / \$0.16 (advanced) |
| Tavily | Extract | `tavily/extract` | \$0.11+ (scales with URL count) |
| Tavily | Map | `tavily/map` | \$0.09 |
| Tavily | Crawl | `tavily/crawl` | \$0.21+ (scales with page limit) |
### Data & Intelligence
| Provider | Endpoint | Slug | Base price |
| -------------- | -------------------------------- | --------------------------------------- | --------------------------------- |
| Alpha Vantage | Intraday Time Series | `alphavantage/time-series-intraday` | \$0.008 |
| Alpha Vantage | Daily Time Series | `alphavantage/time-series-daily` | \$0.008 |
| Alpha Vantage | Weekly Time Series | `alphavantage/time-series-weekly` | \$0.008 |
| Alpha Vantage | Monthly Time Series | `alphavantage/time-series-monthly` | \$0.008 |
| Alpha Vantage | Global Quote | `alphavantage/global-quote` | \$0.008 |
| Alpha Vantage | Symbol Search | `alphavantage/symbol-search` | \$0.008 |
| Alpha Vantage | Market Status | `alphavantage/market-status` | \$0.008 |
| Alpha Vantage | Top Gainers & Losers | `alphavantage/top-gainers-losers` | \$0.008 |
| Alpha Vantage | News Sentiment | `alphavantage/news-sentiment` | \$0.008 |
| Alpha Vantage | Earnings Call Transcript | `alphavantage/earnings-call-transcript` | \$0.008 |
| Alpha Vantage | Company Overview | `alphavantage/company-overview` | \$0.008 |
| Alpha Vantage | Income Statement | `alphavantage/income-statement` | \$0.008 |
| Alpha Vantage | Balance Sheet | `alphavantage/balance-sheet` | \$0.008 |
| Alpha Vantage | Cash Flow | `alphavantage/cash-flow` | \$0.008 |
| Alpha Vantage | Earnings | `alphavantage/earnings` | \$0.008 |
| Alpha Vantage | Currency Exchange Rate | `alphavantage/currency-exchange-rate` | \$0.008 |
| Alpha Vantage | FX Daily | `alphavantage/fx-daily` | \$0.008 |
| Alpha Vantage | Crypto Exchange Rate | `alphavantage/crypto-exchange-rate` | \$0.008 |
| Alpha Vantage | Digital Currency Daily | `alphavantage/digital-currency-daily` | \$0.008 |
| Alpha Vantage | Commodity Price | `alphavantage/commodity-price` | \$0.008 |
| Alpha Vantage | Economic Indicator | `alphavantage/economic-indicator` | \$0.008 |
| Alpha Vantage | SMA (Simple Moving Average) | `alphavantage/sma` | \$0.008 |
| Alpha Vantage | EMA (Exponential Moving Average) | `alphavantage/ema` | \$0.008 |
| Alpha Vantage | MACD | `alphavantage/macd` | \$0.008 |
| Alpha Vantage | RSI (Relative Strength Index) | `alphavantage/rsi` | \$0.008 |
| Alpha Vantage | Bollinger Bands | `alphavantage/bbands` | \$0.008 |
| Apollo | People Enrichment | `apollo/people-enrichment` | \$0.038-\$0.318 |
| Apollo | Bulk People Enrichment | `apollo/bulk-people-enrichment` | \$0.038-\$0.318/person |
| Apollo | Organization Enrichment | `apollo/org-enrichment` | \$0.038 |
| Apollo | Bulk Organization Enrichment | `apollo/bulk-org-enrichment` | \$0.038/org |
| Apollo | People Search | `apollo/people-search` | \$0.005 |
| Apollo | Organization Search | `apollo/org-search` | \$0.005 |
| Apollo | Organization Job Postings | `apollo/job-postings` | \$0.005 |
| Apollo | News Articles Search | `apollo/news-search` | \$0.005 |
| BuiltWith | Domain Lookup | `builtwith/domain` | \$0.055 |
| BuiltWith | Technology Lists | `builtwith/lists` | \$0.055 |
| BuiltWith | Relationships | `builtwith/relationships` | \$0.055 |
| BuiltWith | Company to URL | `builtwith/company-to-url` | \$0.055 |
| BuiltWith | Tags | `builtwith/tags` | \$0.055 |
| BuiltWith | Product Search | `builtwith/product` | \$0.055 |
| BuiltWith | Recommendations | `builtwith/recommendations` | \$0.035 |
| BuiltWith | Redirects | `builtwith/redirects` | \$0.035 |
| BuiltWith | Keywords | `builtwith/keywords` | \$0.035 |
| BuiltWith | Trends | `builtwith/trends` | \$0.035 |
| BuiltWith | Trust | `builtwith/trust` | \$0.035 |
| BuiltWith | Free Summary | `builtwith/free` | \$0.015 |
| Clado | Deep Research | `clado/deep-research` | \$0.01/result |
| Clado | Deep Research Status | `clado/deep-research-status` | \$0.003 |
| Clado | Cancel Deep Research | `clado/deep-research-cancel` | \$0.003 |
| Clado | Deep Research More | `clado/deep-research-more` | \$0.01/result |
| Clado | Contact Enrichment | `clado/contacts` | \$0.04-\$0.14 |
| Clado | Scrape LinkedIn | `clado/scrape` | \$0.023 |
| Clado | LinkedIn Profile | `clado/linkedin-profile` | \$0.013 |
| Clado | Post Reactions | `clado/post-reactions` | \$0.013 |
| Clado | Bulk Contact Enrichment | `clado/bulk-contacts` | \$0.04+/contact |
| Clado | Bulk Contacts Status | `clado/bulk-contacts-status` | \$0.003 |
| Diffbot KG | Search (DQL) | `diffbot-kg/search` | \$0.03–\$1.50 (25 credits/entity) |
| Diffbot KG | Enhance | `diffbot-kg/enhance` | \$0.03 (\$0.12 with refresh) |
| Hunter | Domain Search | `hunter/domain-search` | \$0.013-\$0.103 |
| Hunter | Discover Companies | `hunter/discover` | \$0.008 |
| Hunter | Email Finder | `hunter/email-finder` | \$0.013 |
| Hunter | Email Verifier | `hunter/email-verifier` | \$0.008 |
| Hunter | Email Enrichment | `hunter/email-enrichment` | \$0.013 |
| Hunter | Company Enrichment | `hunter/company-enrichment` | \$0.013 |
| Hunter | Combined Enrichment | `hunter/combined-enrichment` | \$0.023 |
| Hunter | Email Count | `hunter/email-count` | \$0.003 |
| IPinfo | IP Lite | `ipinfo/ip-lite` | \$0.001 |
| Mapbox | Forward Geocode | `mapbox/geocode-forward` | \$0.00375 |
| Mapbox | Reverse Geocode | `mapbox/geocode-reverse` | \$0.00375 |
| Mapbox | Directions | `mapbox/directions` | \$0.005 |
| Mapbox | Matrix | `mapbox/matrix` | \$0.002/element |
| Mapbox | Isochrone | `mapbox/isochrone` | \$0.005 |
| Mapbox | Map Matching | `mapbox/map-matching` | \$0.005 |
| Mapbox | Static Image | `mapbox/static-image` | \$0.004 |
| Mapbox | Tilequery | `mapbox/tilequery` | \$0.005 |
| OpenWeather | Current Weather | `openweather/current-weather` | \$0.003 + \$0.003 fee |
| OpenWeather | 5-Day Forecast | `openweather/forecast-5day` | \$0.005 + \$0.003 fee |
| OpenWeather | Air Quality | `openweather/air-quality` | \$0.003 + \$0.003 fee |
| OpenWeather | Geocode | `openweather/geocode` | \$0.002 + \$0.003 fee |
| OpenWeather | Reverse Geocode | `openweather/reverse-geocode` | \$0.002 + \$0.003 fee |
| OpenWeather | One Call — Full Forecast | `openweather/onecall` | \$0.007 + \$0.003 fee |
| OpenWeather | Weather Overview | `openweather/weather-overview` | \$0.007 + \$0.003 fee |
| RentCast | Property Records | `rentcast/properties` | \$0.033 |
| RentCast | Property by ID | `rentcast/property-by-id` | \$0.033 |
| RentCast | Random Properties | `rentcast/random-properties` | \$0.033 |
| RentCast | Value Estimate (AVM) | `rentcast/value-estimate` | \$0.033 |
| RentCast | Rent Estimate | `rentcast/rent-estimate` | \$0.033 |
| RentCast | Sale Listings | `rentcast/sale-listings` | \$0.033 |
| RentCast | Sale Listing by ID | `rentcast/sale-listing-by-id` | \$0.033 |
| RentCast | Rental Listings | `rentcast/rental-listings` | \$0.033 |
| RentCast | Rental Listing by ID | `rentcast/rental-listing-by-id` | \$0.033 |
| RentCast | Market Statistics | `rentcast/markets` | \$0.033 |
| Whitepages Pro | List States | `whitepages/list-states` | \$0.005 |
| Whitepages Pro | List Counties | `whitepages/list-counties` | \$0.005 |
| Wolfram\|Alpha | Short Answer | `wolframalpha/short-answer` | \$0.055 |
| Wolfram\|Alpha | Spoken Result | `wolframalpha/spoken` | \$0.055 |
| Wolfram\|Alpha | Full Results | `wolframalpha/full-results` | \$0.055 |
| Wolfram\|Alpha | Simple (Image) | `wolframalpha/simple` | \$0.055 |
| ZeroBounce | Validate Email | `zerobounce/validate-email` | \$0.0225 |
| ZeroBounce | Validate Email Batch | `zerobounce/validate-batch` | \$0.023–\$3.903 |
### Finance & Markets
| Provider | Endpoint | Slug | Base price |
| ---------------------- | ------------------- | --------------------------- | --------------------- |
| EDGAR (SEC) | Company Submissions | `edgar/company-submissions` | \$0.005 + \$0.003 fee |
| EDGAR (SEC) | Company Facts | `edgar/company-facts` | \$0.005 + \$0.003 fee |
| EDGAR (SEC) | Company Concept | `edgar/company-concept` | \$0.005 + \$0.003 fee |
| EDGAR Full-Text Search | Search Filings | `edgar-search/search` | \$0.005 + \$0.003 fee |
### Web3 & Onchain
| Provider | Endpoint | Slug | Base price |
| --------- | ----------------------- | ------------------------------ | ---------- |
| CoinGecko | Simple Price | `coingecko/simple-price` | \$0.06 |
| CoinGecko | Token Price by Contract | `coingecko/simple-token-price` | \$0.06 |
| CoinGecko | Coins Markets | `coingecko/coins-markets` | \$0.06 |
| CoinGecko | Coin Data | `coingecko/coin-data` | \$0.06 |
| CoinGecko | Coins List | `coingecko/coins-list` | \$0.06 |
| CoinGecko | Search | `coingecko/search` | \$0.06 |
| CoinGecko | Trending | `coingecko/trending` | \$0.06 |
| CoinGecko | Exchange Rates | `coingecko/exchange-rates` | \$0.06 |
| CoinGecko | Global | `coingecko/global` | \$0.06 |
| CoinGecko | Global DeFi | `coingecko/global-defi` | \$0.06 |
| CoinGecko | Market Chart | `coingecko/market-chart` | \$0.06 |
| CoinGecko | Coin History | `coingecko/coin-history` | \$0.06 |
| CoinGecko | Categories | `coingecko/categories` | \$0.06 |
| CoinGecko | Top Gainers & Losers | `coingecko/top-gainers-losers` | \$0.06 |
| CoinGecko | Exchanges | `coingecko/exchanges` | \$0.06 |
### Social
| Provider | Endpoint | Slug | Base price |
| ----------- | -------------------- | ----------------------- | ---------- |
| Billboard | Post | `billboard/post` | \$0.01+ |
| Billboard | Get Price | `billboard/get-price` | \$0.001 |
| X (Twitter) | Tweet Lookup | `x/tweet-lookup` | \$0.016 |
| X (Twitter) | Tweets Batch Lookup | `x/tweets-lookup` | \$0.016 |
| X (Twitter) | Search Recent Tweets | `x/tweet-search-recent` | \$0.016 |
| X (Twitter) | Recent Tweet Counts | `x/tweet-count-recent` | \$0.016 |
| X (Twitter) | Quote Tweets | `x/tweet-quotes` | \$0.016 |
| X (Twitter) | Retweeted By | `x/tweet-retweeted-by` | \$0.016 |
| X (Twitter) | User Lookup | `x/user-lookup` | \$0.016 |
| X (Twitter) | Users Batch Lookup | `x/users-lookup` | \$0.016 |
| X (Twitter) | User by Username | `x/user-by-username` | \$0.016 |
| X (Twitter) | Users by Usernames | `x/users-by-usernames` | \$0.016 |
| X (Twitter) | User Tweets | `x/user-tweets` | \$0.016 |
| X (Twitter) | User Mentions | `x/user-mentions` | \$0.016 |
| X (Twitter) | User Followers | `x/user-followers` | \$0.016 |
| X (Twitter) | User Following | `x/user-following` | \$0.016 |
| X (Twitter) | Trending Topics | `x/trends` | \$0.016 |
### Security & Compliance
| Provider | Endpoint | Slug | Base price |
| ------------------ | ------------------------- | -------------------------------------- | ------------ |
| OFAC Sanctions API | Sanctions Screening | `ofac/screen` | \$0.012/case |
| OFAC Sanctions API | Sanctions Search | `ofac/search` | \$0.012/case |
| VirusTotal | File Report | `virustotal/file-report` | \$0.055 |
| VirusTotal | URL Report | `virustotal/url-report` | \$0.055 |
| VirusTotal | Domain Report | `virustotal/domain-report` | \$0.055 |
| VirusTotal | IP Address Report | `virustotal/ip-report` | \$0.055 |
| VirusTotal | Scan URL | `virustotal/url-scan` | \$0.085 |
| VirusTotal | Analysis Status | `virustotal/analysis` | \$0.055 |
| VirusTotal | Search | `virustotal/search` | \$0.085 |
| VirusTotal | DNS Resolution | `virustotal/dns-resolution` | \$0.055 |
| VirusTotal | File Comments | `virustotal/file-comments` | \$0.055 |
| VirusTotal | Domain Comments | `virustotal/domain-comments` | \$0.055 |
| VirusTotal | IP Comments | `virustotal/ip-comments` | \$0.055 |
| VirusTotal | Popular Threat Categories | `virustotal/popular-threat-categories` | \$0.055 |
| VirusTotal | URL Comments | `virustotal/url-comments` | \$0.055 |
| VirusTotal | File Votes | `virustotal/file-votes` | \$0.055 |
| VirusTotal | URL Votes | `virustotal/url-votes` | \$0.055 |
| VirusTotal | Domain Votes | `virustotal/domain-votes` | \$0.055 |
| VirusTotal | IP Votes | `virustotal/ip-votes` | \$0.055 |
| VirusTotal | File Behaviours | `virustotal/file-behaviours` | \$0.055 |
| VirusTotal | Latest Comments | `virustotal/latest-comments` | \$0.055 |
| VirusTotal | Attack Tactic | `virustotal/attack-tactic` | \$0.055 |
| VirusTotal | Attack Technique | `virustotal/attack-technique` | \$0.055 |
### Developer Tools
| Provider | Endpoint | Slug | Base price |
| ------------- | ------------------- | ----------------------- | ------------------ |
| Judge0 | Execute Code | `judge0/execute-code` | \$0.006 |
| Judge0 | Submit Code (Async) | `judge0/submit-code` | \$0.006 |
| Judge0 | Get Submission | `judge0/get-submission` | \$0.005 (fee only) |
| Judge0 | List Languages | `judge0/list-languages` | \$0.005 (fee only) |
| Judge0 | List Statuses | `judge0/list-statuses` | \$0.005 (fee only) |
| ScreenshotOne | Take Screenshot | `screenshotone/take` | \$0.055 |
## System-managed capability routes
These Recipes combine providers for a complete task. The table reflects the
directory snapshot; see [Recipes](/locus-pro/individual/recipes) for the full
guide, including Web Extract and GTM Enrichment.
| Capability | Endpoint | Slug | Base price |
| --------------------- | ------------- | ---------------------------- | ---------------------------------- |
| Multi-Provider Router | Web Search | `router/web-search` | Sum of successful underlying calls |
| Multi-Provider Router | Web Research | `router/web-research` | Sum of successful underlying calls |
| Locus Travel | Flight Search | `locus-travel/flight-search` | Sum of successful underlying calls |
Enterprise integrations can use [Recipe API calls](/locus-pro/capability-routing).
## Parse marketplace
Browse 3,290 Parse listings across 24 categories, from public datasets to
travel and commerce. Each entry links to its source and lists the available
API operations.
View all Parse APIs and endpoints by category, with exact slugs.
## Live-quoted services
These independent services add specialized APIs to the catalog. They use your
Locus balance and quote a price for each request. Have your agent inspect the
service and quote before running it.
| Provider | Endpoint | Slug | Price |
| ------------------ | ------------------------- | ---------------------------------------------------------------------- | ----------- |
| 402 API | AI Extract | `x402-402-com-tr-api-x402-ai-extract/call` | live-quoted |
| Action | Webhook | `x402-action402-vercel-app-api-execute-webhook/call` | live-quoted |
| Agent Utility | Image Generate | `x402-x402-agentutility-ai-image-generate/call` | live-quoted |
| Agent Utility | Image Generate Pro | `x402-x402-agentutility-ai-image-generate-pro/call` | live-quoted |
| Agent402 | LLM | `x402-agent402-tools-api-llm/call` | live-quoted |
| Agent402 | UUID | `x402-agent402-tools-api-uuid/call` | live-quoted |
| Agentic JP | Stats | `x402-houjin-agentic-jp-com-stats/call` | live-quoted |
| AgentPay | Verified Route | `x402-agentpay-tools-tools-verified-route-call/call` | live-quoted |
| AgentRes | Create | `x402-agentres-dev-api-reservation-jobs-create/call` | live-quoted |
| Atelier | Generate Image | `x402-api-useatelier-ai-api-x402-pay-svc-1780812536114-y6pg8e7aw/call` | live-quoted |
| Auto.exchange | call | `mpp-autoexchange/call` | live-quoted |
| BAGS | API Index | `x402-getbags-app-api-v1/call` | live-quoted |
| Baseten Model APIs | call | `mpp-orth-baseten/call` | live-quoted |
| Bitrefill | Detail | `x402-api-bitrefill-com-x402-products-detail/call` | live-quoted |
| DELX | Image | `x402-api-delx-ai-api-v1-x402-image/call` | live-quoted |
| ForgeMesh | Base | `x402-voice-forgemesh-io-v1-tts-base/call` | live-quoted |
| Hugen | Symbols | `x402-tick-hugen-tokyo-tick-symbols/call` | live-quoted |
| Interzoid | Match Full Name | `x402-api-interzoid-com-getfullnamematch/call` | live-quoted |
| Interzoid | Translate to Any Language | `x402-api-interzoid-com-translatetoany/call` | live-quoted |
| Interzoid | Translate to English | `x402-api-interzoid-com-translatetoenglish/call` | live-quoted |
| Linked Panda | Email | `x402-api-linkedpanda-com-agent-v1-profiles-email/call` | live-quoted |
| Linked Panda | Enrich | `x402-api-linkedpanda-com-agent-v1-profiles-enrich/call` | live-quoted |
| Lone Star Oracle | Agri Report | `x402-agri-lonestaroracle-xyz-report/call` | live-quoted |
| Moltalyzer | Digests | `x402-api-moltalyzer-xyz-api-moltbook-digests/call` | live-quoted |
| molty.cash | call | `mpp-moltycash/call` | live-quoted |
| NetIntel | Messages | `x402-netintel-dev-messages/call` | live-quoted |
| NetIntel | Schema Parse Extract | `x402-netintel-dev-schema-parse-extract/call` | live-quoted |
| NetIntel | Web Extract | `x402-netintel-dev-web-extract/call` | live-quoted |
| OneShot Agent | Profile | `x402-win-oneshotagent-com-v1-tools-enrich-profile/call` | live-quoted |
| Papercut | call | `mpp-papercut/call` | live-quoted |
| Relay Station | Match | `x402-api-relaystation-ai-v1-screening-match/call` | live-quoted |
| SchemaSure | Extract | `x402-schemasure-com-v2-extract/call` | live-quoted |
| Signalis | Narratives | `x402-api-signalis-dev-v1-pulse-narratives/call` | live-quoted |
| Skim | Latest | `x402-skim402-com-api-v2-signal-ai-news-latest/call` | live-quoted |
| Skim | Read | `x402-skim402-com-api-v2-read/call` | live-quoted |
| Stable Phone | call | `mpp-stablephone/call` | live-quoted |
| Stable Upload | Upload | `x402-stableupload-dev-api-upload/call` | live-quoted |
| Suede AI | Create Music | `x402-app-suedeai-ai-create-music/call` | live-quoted |
| TensorFeed | Directory | `x402-tensorfeed-ai-api-premium-agents-directory/call` | live-quoted |
| TensorFeed | Exposure | `x402-tensorfeed-ai-api-premium-ai-safety-incidents-exposure/call` | live-quoted |
| TensorFeed | Whats New | `x402-tensorfeed-ai-api-premium-whats-new/call` | live-quoted |
| VoidFeed | Fact Feed Latest | `x402-voidfeed-ai-v1-content-fact-feed-latest/call` | live-quoted |
| Webber Sites | Calc | `x402-api-webbersites-com-api-calc/call` | live-quoted |
| Webber Sites | Messages | `x402-api-webbersites-com-v1-messages/call` | live-quoted |
| Word of the Day | Word Of The Day | `x402-x402wordoftheday-vercel-app-api-word-of-the-day/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| ------------------- | ----------------------- | -------------------------------------------------------------------- | ----------- |
| Agent Utility | Recent Tweet Search | `x402-x402-agentutility-ai-recent-tweet-search/call` | live-quoted |
| Agent Utility | Tweets Search | `x402-x402-agentutility-ai-tweets-search/call` | live-quoted |
| Agent Utility | Twitter Search | `x402-x402-agentutility-ai-twitter-search/call` | live-quoted |
| Agent402 | Render | `x402-agent402-tools-api-render/call` | live-quoted |
| Agent402 | Search | `x402-agent402-tools-api-search/call` | live-quoted |
| Agentic JP | Search | `x402-diet-agentic-jp-com-members-search/call` | live-quoted |
| Agents Tools | Search | `x402-api-agentstools-dev-search/call` | live-quoted |
| Andi Search API | call | `mpp-orth-andi/call` | live-quoted |
| API Toll | Search | `x402-reddit-apitoll-cloud-v1-reddit-search/call` | live-quoted |
| Bitrefill | Search | `x402-api-bitrefill-com-x402-gift-cards-search/call` | live-quoted |
| Boon Protocol | Routes | `x402-api-boonprotocol-com-api-v1-x402-routes/call` | live-quoted |
| DevVizion | Outline | `x402-x402-devvizion-com-v0-outline/call` | live-quoted |
| ForgeMesh | Stats | `x402-ads-forgemesh-io-api-network-stats/call` | live-quoted |
| Greeneris | LEI | `x402-data-greeneris-io-v1-global-lei/call` | live-quoted |
| HireScrape | TikTok | `x402-hirescrape-com-api-tools-tiktok/call` | live-quoted |
| Interzoid | Get X User Profile | `x402-api-interzoid-com-getxuserprofile/call` | live-quoted |
| Linked Panda | Profiles Search | `x402-api-linkedpanda-com-agent-v1-profiles-search/call` | live-quoted |
| Linkup API | call | `mpp-orth-linkup/call` | live-quoted |
| Lion x402 | Web Search JSON | `x402-lionx402-com-api-x402-web-search-json/call` | live-quoted |
| Open Web Ninja | Search | `x402-x402-openwebninja-com-local-business-data-search/call` | live-quoted |
| Open Web Ninja | Search Events | `x402-x402-openwebninja-com-realtime-events-data-search-events/call` | live-quoted |
| Open Web Ninja | Search Full | `x402-x402-openwebninja-com-realtime-web-search-search-full/call` | live-quoted |
| ReadX | Search | `x402-readx-sh-api-search/call` | live-quoted |
| ReadX | Tweets | `x402-readx-sh-api-search-tweets/call` | live-quoted |
| Seltz | call | `mpp-orth-seltz/call` | live-quoted |
| SerpApi | call | `mpp-serpapi/call` | live-quoted |
| Serper | call | `mpp-orth-serper/call` | live-quoted |
| Sirenic | Search French Companies | `x402-api-sirenic-eu-v1-recherche/call` | live-quoted |
| SocialFetch | Search | `x402-api-socialfetch-dev-v1-twitter-search/call` | live-quoted |
| Stable Browser | Sessions | `x402-stablebrowser-dev-api-sessions/call` | live-quoted |
| Stable Enrich | Company Search | `x402-stableenrich-dev-api-fullenrich-company-search/call` | live-quoted |
| Stable Enrich | People Search | `x402-stableenrich-dev-api-fullenrich-people-search/call` | live-quoted |
| Stable Enrich | Search | `x402-stableenrich-dev-api-reddit-search/call` | live-quoted |
| Stable Estate | Apartments Search | `x402-stableestate-dev-api-apartments-search/call` | live-quoted |
| Stable Estate | Properties Search | `x402-stableestate-dev-api-properties-search/call` | live-quoted |
| Stable Flare | Screenshot | `x402-stableflare-dev-api-browser-screenshot/call` | live-quoted |
| Stable Jobs | Job Search | `x402-stablejobs-dev-api-coresignal-job-search/call` | live-quoted |
| Stable Social | Channel | `x402-stablesocial-dev-api-sc-youtube-channel/call` | live-quoted |
| Stable Social | Channel Videos | `x402-stablesocial-dev-api-sc-youtube-channel-videos/call` | live-quoted |
| Stable Social | Profile | `x402-stablesocial-dev-api-sc-tiktok-profile/call` | live-quoted |
| Stable Social | Reels | `x402-stablesocial-dev-api-sc-instagram-user-reels/call` | live-quoted |
| Stable Tickets | Search | `x402-stabletickets-dev-api-events-search/call` | live-quoted |
| Stable Travel | Booking | `x402-stabletravel-dev-api-google-flights-booking/call` | live-quoted |
| Stable Travel | Search | `x402-stabletravel-dev-api-seats-aero-search/call` | live-quoted |
| Tako via Orthogonal | call | `mpp-orth-tako/call` | live-quoted |
| TensorFeed | Citation Velocity | `x402-tensorfeed-ai-api-premium-research-citation-velocity/call` | live-quoted |
| Twit | Tweets Search | `x402-x402-twit-sh-tweets-search/call` | live-quoted |
| Twit | Users Search | `x402-x402-twit-sh-users-search/call` | live-quoted |
| Underscore Done | Capture | `x402-screenshots-underscoredone-com-capture/call` | live-quoted |
| x402 Data API | Agent Accessibility | `x402-api-x402dataapi-com-v1-agent-accessibility/call` | live-quoted |
| x402 Node | Social | `x402-api-x402node-dev-web-social/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| ---------------- | ------------------- | ----------------------------------------------------------------------------- | ----------- |
| Agent Exchange | Prices | `x402-store-agentexchange-work-crypto-prices/call` | live-quoted |
| AgentRes | Book | `x402-agentres-dev-api-book/call` | live-quoted |
| AI Dress | IXS Finance Agent | `x402-api-aidress-ai-pay-agent-api-dev-v2-ixs-finance/call` | live-quoted |
| Alchemy | call | `mpp-alchemy/call` | live-quoted |
| Allium | call | `mpp-allium/call` | live-quoted |
| API Toll | EVM Gas | `x402-evm-gas-apitoll-cloud-v1-evm-gas/call` | live-quoted |
| API Toll | Global | `x402-crypto-apitoll-cloud-v1-crypto-global/call` | live-quoted |
| API Toll | Price | `x402-crypto-apitoll-cloud-v1-crypto-price/call` | live-quoted |
| Apify | Prepaid Tokens | `x402-agi-apify-com-protocols-x402-prepaid-tokens/call` | live-quoted |
| ARKM | Balances Address | `x402-api-arkm-com-x402-balances-address/call` | live-quoted |
| ARKM | Token | `x402-api-arkm-com-x402-intelligence-token/call` | live-quoted |
| BlockRun | Leaderboard | `x402-blockrun-ai-api-v1-pm-polymarket-leaderboard/call` | live-quoted |
| Boon Protocol | Graph | `x402-api-boonprotocol-com-api-v1-x402-graph/call` | live-quoted |
| Capminal AI | Research | `x402-capminal-ai-api-x402-research/call` | live-quoted |
| Cheap Tokens | Buy | `x402-cheaptokens-ai-api-buy/call` | live-quoted |
| ClawFetch | Fetch | `x402-api-clawfetch-ai-fetch/call` | live-quoted |
| Codex | call | `mpp-codex/call` | live-quoted |
| CoinMarketCap | Latest | `x402-pro-api-coinmarketcap-com-x402-v4-dex-pairs-quotes-latest/call` | live-quoted |
| CoinMarketCap | Search | `x402-pro-api-coinmarketcap-com-x402-v1-dex-search/call` | live-quoted |
| Conduit | call | `mpp-conduit/call` | live-quoted |
| Creative Tim | User Payment | `x402-x402-creative-tim-com-shadcn-blocks-user-payment/call` | live-quoted |
| Deep3 | Wave 1 | `x402-mcp-deep3-ai-tools-wave-1/call` | live-quoted |
| Interzoid | Get IP Profile | `x402-api-interzoid-com-getipprofile/call` | live-quoted |
| IXS Finance | Vaults | `x402-api-dev-v2-ixs-finance-x402-vaults/call` | live-quoted |
| Laso | Auth | `x402-laso-finance-auth/call` | live-quoted |
| Lion x402 | Wallet Screen JSON | `x402-lionx402-com-api-x402-wallet-screen-json/call` | live-quoted |
| Lone Star Oracle | Flow | `x402-options-lonestaroracle-xyz-flow/call` | live-quoted |
| Lone Star Oracle | Supply Report | `x402-supply-lonestaroracle-xyz-report/call` | live-quoted |
| LoyalSpark | Balance | `x402-api-loyalspark-online-x402-gateway-recipient-api-balance/call` | live-quoted |
| LoyalSpark | Balances | `x402-api-loyalspark-online-x402-gateway-recipient-api-balances/call` | live-quoted |
| LoyalSpark | Cancel Offer | `x402-api-loyalspark-online-x402-gateway-recipient-api-cancel-offer/call` | live-quoted |
| LoyalSpark | Offers | `x402-api-loyalspark-online-x402-gateway-recipient-api-offers/call` | live-quoted |
| LoyalSpark | Prepare Transfer | `x402-api-loyalspark-online-x402-gateway-recipient-api-prepare-transfer/call` | live-quoted |
| LoyalSpark | Rewards | `x402-api-loyalspark-online-x402-gateway-recipient-api-rewards/call` | live-quoted |
| Nansen | call | `mpp-nansen/call` | live-quoted |
| Nansen | Current Balance | `x402-api-nansen-ai-api-v1-profiler-address-current-balance/call` | live-quoted |
| Nansen | Flows | `x402-api-nansen-ai-api-v1-tgm-flows/call` | live-quoted |
| Nansen | Historical Balances | `x402-api-nansen-ai-api-v1-profiler-address-historical-balances/call` | live-quoted |
| Nansen | PnL | `x402-api-nansen-ai-api-v1-profiler-address-pnl/call` | live-quoted |
| Nansen | PnL Summary | `x402-api-nansen-ai-api-v1-profiler-address-pnl-summary/call` | live-quoted |
| Nansen | Related Wallets | `x402-api-nansen-ai-api-v1-profiler-address-related-wallets/call` | live-quoted |
| Nansen | Transactions | `x402-api-nansen-ai-api-v1-profiler-address-transactions/call` | live-quoted |
| Nansen | Who Bought Sold | `x402-api-nansen-ai-api-v1-tgm-who-bought-sold/call` | live-quoted |
| NodeFlare | Base | `x402-rpc-nodeflare-app-base-x402/call` | live-quoted |
| OneSource | Block Number | `x402-api-onesource-io-api-chain-block-number/call` | live-quoted |
| OneSource | ERC-20 Balance | `x402-api-onesource-io-api-chain-erc20-balance/call` | live-quoted |
| OneSource | ERC-20 Transfers | `x402-api-onesource-io-api-chain-erc20-transfers/call` | live-quoted |
| OneSource | ERC-721 Tokens | `x402-api-onesource-io-api-chain-erc721-tokens/call` | live-quoted |
| OneSource | Live Balance | `x402-api-onesource-io-api-chain-live-balance/call` | live-quoted |
| OneSource | Network Info | `x402-api-onesource-io-api-chain-network-info/call` | live-quoted |
| OneSource | NFT Metadata | `x402-api-onesource-io-api-chain-nft-metadata/call` | live-quoted |
| OneSource | Total Supply | `x402-api-onesource-io-api-chain-total-supply/call` | live-quoted |
| Otto AI | DeFi Analytics | `x402-x402-ottoai-services-defi-analytics/call` | live-quoted |
| Otto AI | Token Details | `x402-x402-ottoai-services-token-details/call` | live-quoted |
| Otto AI | Yield Markets | `x402-x402-ottoai-services-yield-markets/call` | live-quoted |
| Ozmium | Arbitrage | `x402-ozmium-org-v1-arbitrage/call` | live-quoted |
| Print Money Lab | Kimchi Premium | `x402-api-printmoneylab-com-api-v1-kimchi-premium/call` | live-quoted |
| Print Money Lab | KR Prices | `x402-api-printmoneylab-com-api-v1-kr-prices/call` | live-quoted |
| Quicknode | call | `mpp-quicknode/call` | live-quoted |
| Spraay | Prices | `x402-gateway-spraay-app-api-v1-prices/call` | live-quoted |
| Stable Studio | Upload | `x402-stablestudio-dev-api-upload/call` | live-quoted |
| Suverse | DEX Trending Pools | `x402-proxy-suverse-io-v1-data-dex-trending-pools/call` | live-quoted |
| Tempo RPC | call | `mpp-rpc/call` | live-quoted |
| Tereno | Invoke | `x402-tereno-xyz-api-v1-capabilities-token-metadata-invoke/call` | live-quoted |
| Tollbooth Swap | Build | `x402-api-tollboothswap-xyz-v1-swap-build/call` | live-quoted |
| Twin3 | Human | `x402-human-twin3-ai-v1-human/call` | live-quoted |
| VAPE | Chain Fees | `x402-vape-x402-vapex402-workers-dev-data-chain-fees/call` | live-quoted |
| VAPE | Chain Overview | `x402-vape-x402-vapex402-workers-dev-data-chain-overview/call` | live-quoted |
| VAPE | Chain Protocols | `x402-vape-x402-vapex402-workers-dev-data-chain-protocols/call` | live-quoted |
| VAPE | DEX Volumes | `x402-vape-x402-vapex402-workers-dev-data-dex-volumes/call` | live-quoted |
| VAPE | Protocol | `x402-vape-x402-vapex402-workers-dev-data-protocol/call` | live-quoted |
| VAPE | Yields | `x402-vape-x402-vapex402-workers-dev-data-yields/call` | live-quoted |
| VibeSprings | Address Risk | `x402-vibesprings-net-api-address-risk/call` | live-quoted |
| VibeSprings | Base Gas | `x402-vibesprings-net-api-price-base-gas/call` | live-quoted |
| VoidFeed | Dataset Latest | `x402-voidfeed-ai-v1-content-extract-dataset-latest/call` | live-quoted |
| x402 Node | Gas Compare | `x402-api-x402node-dev-chain-gas-compare/call` | live-quoted |
| x402 Node | Honeypot | `x402-api-x402node-dev-chain-honeypot/call` | live-quoted |
| x402 Node | Protocol TVL | `x402-api-x402node-dev-defi-protocol-tvl/call` | live-quoted |
| x402 Node | Smart Money Score | `x402-api-x402node-dev-chain-smart-money-score/call` | live-quoted |
| x402scan | Facilitators | `x402-x402scan-com-api-x402-facilitators/call` | live-quoted |
| x402scan | Merchants | `x402-x402scan-com-api-x402-merchants/call` | live-quoted |
| x402scan | Origin | `x402-x402scan-com-api-x402-registry-origin/call` | live-quoted |
| x402scan | Resources | `x402-x402scan-com-api-x402-resources/call` | live-quoted |
| x402scan | Search | `x402-x402scan-com-api-x402-resources-search/call` | live-quoted |
| x402scan | Stats | `x402-x402scan-com-api-x402-facilitators-stats/call` | live-quoted |
| Yield | List All Yields | `x402-mcp-yield-xyz-x402-yields-get-all/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| -------------------- | --------------------- | ---------------------------------------------------------------------------- | ----------- |
| Agent402 | Random | `x402-agent402-tools-api-random/call` | live-quoted |
| Agent402 | Stock Quote | `x402-agent402-tools-api-stock-quote/call` | live-quoted |
| AgentPay | Pre Trade Check | `x402-agentpay-tools-tools-pre-trade-check-call/call` | live-quoted |
| AI Dress | Crypto News Agent | `x402-api-aidress-ai-pay-agent-ottoai-crypto-news/call` | live-quoted |
| AI Dress | EDGAR Research Agent | `x402-api-aidress-ai-pay-agent-edgar-apitoll-cloud/call` | live-quoted |
| Anchor x402 | Roll | `x402-api-anchor-x402-com-v1-roll/call` | live-quoted |
| API Toll | Base Gas | `x402-gas-apitoll-cloud-v1-base-gas/call` | live-quoted |
| API Toll | News | `x402-news-apitoll-cloud-v1-cointelegraph-news/call` | live-quoted |
| API Toll | Perps | `x402-crypto-apitoll-cloud-v1-crypto-perps/call` | live-quoted |
| API Toll | Sentiment | `x402-crypto-apitoll-cloud-v1-crypto-sentiment/call` | live-quoted |
| Bazaar Gateway | Crypto Prices | `x402-bazaar-gateway-vercel-app-api-crypto-prices/call` | live-quoted |
| Bitrefill | Create | `x402-api-bitrefill-com-x402-invoice-create/call` | live-quoted |
| BlockRun | AAPL | `x402-blockrun-web-vbsbhh7lea-uc-a-run-app-api-v1-stocks-us-price-aapl/call` | live-quoted |
| BlockRun | Events | `x402-blockrun-ai-api-v1-pm-polymarket-events/call` | live-quoted |
| BlockRun | Kalshi Markets | `x402-blockrun-ai-api-v1-pm-kalshi-markets/call` | live-quoted |
| BlockRun | Polymarket Markets | `x402-blockrun-ai-api-v1-pm-polymarket-markets/call` | live-quoted |
| BlockRun | Search | `x402-blockrun-ai-api-v1-pm-markets-search/call` | live-quoted |
| ClaudeLines | Register | `x402-claudelines-com-api-register/call` | live-quoted |
| Coil | Regime | `x402-coil-trade-api-board-regime/call` | live-quoted |
| Drip Metrics | Kyle Lambda | `x402-api-dripmetrics-ai-metrics-kyle-lambda/call` | live-quoted |
| Drip Metrics | VPIN | `x402-api-dripmetrics-ai-metrics-vpin/call` | live-quoted |
| DripStack | Stock Picks | `x402-dripstack-xyz-api-v1-stock-picks/call` | live-quoted |
| FastDB | Odds | `x402-md-fastdb-in-pulse-odds/call` | live-quoted |
| Glassnode | Metrics | `x402-x402-glassnode-com-v1-metadata-metrics/call` | live-quoted |
| Glassnode | MVRV | `x402-x402-glassnode-com-v1-metrics-market-mvrv/call` | live-quoted |
| Glassnode | USD Closing Price | `x402-x402-glassnode-com-v1-metrics-market-price-usd-close/call` | live-quoted |
| IsoCast | Spot | `x402-api-isocast-dev-v1-spot/call` | live-quoted |
| Kronos Signals | DOGE | `x402-kronossignals-com-api-v1-forecast-doge/call` | live-quoted |
| Kronos Signals | Fear Greed | `x402-kronossignals-com-api-v1-fear-greed/call` | live-quoted |
| Kronos Signals | Forecast BTC | `x402-kronossignals-com-api-v1-forecast-btc/call` | live-quoted |
| Kronos Signals | Liquidations BTC | `x402-kronossignals-com-api-v1-liquidations-btc/call` | live-quoted |
| Kronos Signals | Price BTC | `x402-kronossignals-com-api-v1-price-btc/call` | live-quoted |
| Laso | Get Card | `x402-laso-finance-get-card/call` | live-quoted |
| Linked Panda | Jobs Search | `x402-api-linkedpanda-com-agent-v1-jobs-search/call` | live-quoted |
| Lone Star Oracle | Macro | `x402-macro-lonestaroracle-xyz-macro/call` | live-quoted |
| Lone Star Oracle | Metals Report | `x402-metals-lonestaroracle-xyz-report/call` | live-quoted |
| MiroShark | Run | `x402-x402-miroshark-xyz-run/call` | live-quoted |
| Mycelia Signal | USD | `x402-api-myceliasignal-com-oracle-price-btc-usd/call` | live-quoted |
| NetIntel | Convert | `x402-netintel-dev-currency-exchange-convert/call` | live-quoted |
| NetIntel | Market | `x402-netintel-dev-crypto-market/call` | live-quoted |
| OrcaTrace | Latest | `x402-api-orcatrace-dev-v1-latest/call` | live-quoted |
| Otto AI | Crypto News | `x402-x402-ottoai-services-crypto-news/call` | live-quoted |
| Otto AI | Funding Rates | `x402-x402-ottoai-services-funding-rates/call` | live-quoted |
| Otto AI | Hyperliquid Market | `x402-x402-ottoai-services-hyperliquid-market/call` | live-quoted |
| Otto AI | TradFi Data | `x402-x402-ottoai-services-tradfi-data/call` | live-quoted |
| Otto AI | Twitter Summary | `x402-x402-ottoai-services-twitter-summary/call` | live-quoted |
| Ozmium | Markets | `x402-ozmium-org-v1-loan-markets/call` | live-quoted |
| Ozmium | Pairs | `x402-ozmium-org-v1-risk-pairs/call` | live-quoted |
| Ozmium | Prices | `x402-ozmium-org-v1-prices/call` | live-quoted |
| PayAPI | Current | `x402-weather-payapi-market-current/call` | live-quoted |
| Proof Ivy | List CryptoSlate News | `x402-library-proofivy-com-cryptoslate-list/call` | live-quoted |
| Random Facts | Random Fact | `x402-randomfactsx402-vercel-app-api-random-fact/call` | live-quoted |
| Shizu | Bounty | `x402-x402-shizu-me-bounty/call` | live-quoted |
| Shizu | Crypto | `x402-x402-shizu-me-crypto/call` | live-quoted |
| Shizu | Funding | `x402-x402-shizu-me-funding/call` | live-quoted |
| Shizu | Rand | `x402-x402-shizu-me-rand/call` | live-quoted |
| Stable People Data | Enrich | `x402-stablepeopledata-dev-api-pdl-company-enrich/call` | live-quoted |
| Stock Trends | Prices Latest | `x402-api-stocktrends-com-v1-prices-latest/call` | live-quoted |
| Stock Trends | Stim Latest | `x402-api-stocktrends-com-v1-stim-latest/call` | live-quoted |
| Sure Why Not | Gas | `x402-quartermaster-surewhynot-app-v1-gas/call` | live-quoted |
| Surplus Intelligence | Completions | `x402-api-surplusintelligence-ai-v1-chat-completions/call` | live-quoted |
| Tickers Feed | Market | `x402-api-tickersfeed-net-crypto-market/call` | live-quoted |
| Underscore Done | CPI | `x402-cpi-report-us-underscoredone-com-cpi/call` | live-quoted |
| VAPE | Stablecoins | `x402-vape-x402-vapex402-workers-dev-data-stablecoins/call` | live-quoted |
| VibeSprings | BTC USD | `x402-vibesprings-net-api-price-btc-usd/call` | live-quoted |
| VibeSprings | Convert | `x402-vibesprings-net-api-exchange-convert/call` | live-quoted |
| VibeSprings | ETH USD | `x402-vibesprings-net-api-price-eth-usd/call` | live-quoted |
| x402 Node | CN Index | `x402-api-x402node-dev-stock-cn-index/call` | live-quoted |
| You | Finance Research | `x402-api-you-com-v1-finance-research/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| ---------------------- | --------------------- | ----------------------------------------------------------- | ----------- |
| 2S | Address | `x402-2s-io-api-geocode-address/call` | live-quoted |
| 2S | Business Days | `x402-2s-io-api-calendar-business-days/call` | live-quoted |
| 2S | Decode WMI | `x402-2s-io-api-vehicle-decode-wmi/call` | live-quoted |
| 2S | Holidays | `x402-2s-io-api-calendar-holidays/call` | live-quoted |
| 2S | Lookup | `x402-2s-io-api-timezone-lookup/call` | live-quoted |
| 2S | Unit | `x402-2s-io-api-convert-unit/call` | live-quoted |
| 2S | VIN Decode | `x402-2s-io-api-vehicle-vin-decode/call` | live-quoted |
| Apex DB | call | `mpp-apex-db/call` | live-quoted |
| AviationStack | call | `mpp-aviationstack/call` | live-quoted |
| Aviato | call | `mpp-orth-aviato/call` | live-quoted |
| Brand.dev API | call | `mpp-orth-brand-dev/call` | live-quoted |
| Bytemine | call | `mpp-orth-bytemine/call` | live-quoted |
| CaptainData | call | `mpp-orth-captaindata/call` | live-quoted |
| Company Enrich | call | `mpp-orth-company-enrich/call` | live-quoted |
| Concierge Intelligence | Concierge Intel Macro | `x402-conc-exe-xyz-api-concierge-intel-macro/call` | live-quoted |
| ContactOut | call | `mpp-orth-contactout/call` | live-quoted |
| Coresignal | call | `mpp-orth-coresignal/call` | live-quoted |
| Crustdata | call | `mpp-orth-crustdata/call` | live-quoted |
| Didit API | call | `mpp-orth-didit/call` | live-quoted |
| Dune | call | `mpp-dune/call` | live-quoted |
| Edges | call | `mpp-orth-edges/call` | live-quoted |
| Fantastic Jobs | call | `mpp-orth-fantastic-jobs/call` | live-quoted |
| Fiber AI API | call | `mpp-orth-fiber/call` | live-quoted |
| FlightAPI | call | `mpp-flightapi/call` | live-quoted |
| Fundable | call | `mpp-orth-fundable/call` | live-quoted |
| GoFlightLabs | call | `mpp-goflightlabs/call` | live-quoted |
| Google Maps | call | `mpp-googlemaps/call` | live-quoted |
| GovLaws | call | `mpp-govlaws/call` | live-quoted |
| Happenstance | call | `mpp-orth-happenstance/call` | live-quoted |
| Hugen | Current | `x402-weather-hugen-tokyo-weather-current/call` | live-quoted |
| Interzoid | Get Global Weather | `x402-api-interzoid-com-getglobalweather/call` | live-quoted |
| InvokeT | Daily | `x402-api-invoket-com-weather-forecast-daily/call` | live-quoted |
| InvokeT | Forecast | `x402-api-invoket-com-weather-forecast/call` | live-quoted |
| InvokeT | Forecast Batch | `x402-api-invoket-com-weather-forecast-batch/call` | live-quoted |
| KicksDB | call | `mpp-kicksdb/call` | live-quoted |
| Nyne.ai | call | `mpp-orth-nyne/call` | live-quoted |
| Ocean.io | call | `mpp-orth-ocean-io/call` | live-quoted |
| OpenFunnel | call | `mpp-orth-openfunnel/call` | live-quoted |
| Openmart | call | `mpp-orth-openmart/call` | live-quoted |
| People Data Labs | call | `mpp-orth-peopledatalabs/call` | live-quoted |
| PredictLeads | call | `mpp-orth-predictleads/call` | live-quoted |
| RecallRadar | call | `mpp-recallradar/call` | live-quoted |
| RxAtlas | call | `mpp-rxatlas/call` | live-quoted |
| Shizu | Weather | `x402-x402-shizu-me-weather/call` | live-quoted |
| Sixtyfour API | call | `mpp-orth-sixtyfour/call` | live-quoted |
| SpyFu | call | `mpp-spyfu/call` | live-quoted |
| SVGSmith | Convert | `x402-api-svgsmith-dev-v1-convert/call` | live-quoted |
| Tako | call | `mpp-tako/call` | live-quoted |
| Time Zones | Convert Timezone | `x402-402timezones-vercel-app-api-convert-timezone/call` | live-quoted |
| Tomba API | call | `mpp-orth-tomba/call` | live-quoted |
| TrialBase DB | call | `mpp-trialbase-db/call` | live-quoted |
| Vindex API | Decode | `x402-api-vindexapi-dev-v1-decode/call` | live-quoted |
| Voygr | call | `mpp-orth-voygr/call` | live-quoted |
| Weight Converter | Convert Weight | `x402-weight402endpoint-vercel-app-api-convert-weight/call` | live-quoted |
| x402 Node | CNY USD | `x402-api-x402node-dev-forex-convert-cny-usd-cny-usd/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| ---------------- | ------------- | -------------------------------------------------- | ----------- |
| AgentFax | call | `mpp-agentfax/call` | live-quoted |
| AgentPhone | call | `mpp-orth-agentphone/call` | live-quoted |
| BotSmith | User | `x402-x402-botsmith-dev-x-user/call` | live-quoted |
| Influencers Club | call | `mpp-orth-influencers-club/call` | live-quoted |
| Scrape Creators | call | `mpp-orth-scrapecreators/call` | live-quoted |
| Stable Deepline | Enrich | `x402-stable-deepline-dev-api-company-enrich/call` | live-quoted |
| Stable Email | call | `mpp-stableemail/call` | live-quoted |
| Stable Enrich | People Enrich | `x402-stableenrich-dev-api-pdl-people-enrich/call` | live-quoted |
| Stable Social | call | `mpp-stablesocial/call` | live-quoted |
| Twit | ID | `x402-x402-twit-sh-tweets-by-id/call` | live-quoted |
| Twit | Replies | `x402-x402-twit-sh-tweets-replies/call` | live-quoted |
| Twit | Tweets | `x402-x402-twit-sh-tweets/call` | live-quoted |
| Twit | User | `x402-x402-twit-sh-tweets-user/call` | live-quoted |
| Twit | Username | `x402-x402-twit-sh-users-by-username/call` | live-quoted |
| Webber Sites | Metadata | `x402-api-webbersites-com-api-seo-metadata/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| -------------- | -------------- | ---------------------------------------------------------- | ----------- |
| AproxPay | Proxy | `x402-proxy-aproxpay-com-v1-proxy/call` | live-quoted |
| AproxPay | Session | `x402-proxy-aproxpay-com-v1-session/call` | live-quoted |
| Code Storage | call | `mpp-codestorage/call` | live-quoted |
| Coin Flip | Coin Flip | `x402-coinflip402-vercel-app-api-coinflip/call` | live-quoted |
| DGDB Store | Listing Doctor | `x402-x402-store-dgdb-workers-dev-v1-listing-doctor/call` | live-quoted |
| Heinrichs Tech | Echo | `x402-app-heinrichstech-com-v1-cdp-echo/call` | live-quoted |
| Horror Story | Horror Story | `x402-horrorstoryapi-vercel-app-api-horror-story/call` | live-quoted |
| InvokeT | Screen | `x402-api-invoket-com-iban-screen/call` | live-quoted |
| Jokes | Jokes | `x402-jokes-endpoint-vercel-app-api-jokes/call` | live-quoted |
| Lady Fortuna | Fortune | `x402-ladyfortunalx402-vercel-app-api-fortune/call` | live-quoted |
| Meme Generator | Generate Meme | `x402-memegeneratorx402-vercel-app-api-generate-meme/call` | live-quoted |
| Object Storage | call | `mpp-storage/call` | live-quoted |
| OmniGuchi | Feed | `x402-omniguchi-0000402-xyz-care-feed/call` | live-quoted |
| OmniGuchi | Pack | `x402-omniguchi-0000402-xyz-care-pack/call` | live-quoted |
| Pinata IPFS | call | `mpp-pinata/call` | live-quoted |
| Riddle | Riddle | `x402-riddlex402-vercel-app-api-riddle/call` | live-quoted |
| Roast | Roast | `x402-roastx402endpoint-vercel-app-api-roast/call` | live-quoted |
| Stable Upload | call | `mpp-stableupload/call` | live-quoted |
| Stable Upload | Site | `x402-stableupload-dev-api-site/call` | live-quoted |
| Trust | Check | `x402-trust402-vercel-app-api-trust-check-x402/call` | live-quoted |
| Useless Facts | Useless Fact | `x402-x402uselessfacts-vercel-app-api-useless-fact/call` | live-quoted |
| x402 Node | Search | `x402-api-x402node-dev-ecom-search/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| -------- | -------- | ------------------------------------------------ | ----------- |
| Spraay | SMS | `x402-gateway-spraay-app-api-v1-notify-sms/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| -------- | -------- | ---------------------------------------- | ----------- |
| Dice | Dice | `x402-dicex402-vercel-app-api-dice/call` | live-quoted |
| Provider | Endpoint | Slug | Price |
| ---------------------- | ---------------------------- | ----------------------------------------------------------------------------------- | ----------- |
| 2Captcha | call | `mpp-twocaptcha/call` | live-quoted |
| 2S | Near | `x402-2s-io-api-airport-near/call` | live-quoted |
| ActionLayer | Poll a task | `x402-actionlayer-poll-task/call` | live-quoted |
| ActionLayer | Reply to a task | `x402-actionlayer-reply-task/call` | live-quoted |
| ActionLayer | Submit a task | `x402-actionlayer-submit-task/call` | live-quoted |
| Affiliate | ASIN To Barcode | `x402-zeroclick-affiliate-com-v1-tools-convert-asin-to-barcode/call` | live-quoted |
| Affiliate | Barcode To ASIN | `x402-zeroclick-affiliate-com-v1-tools-convert-barcode-to-asin/call` | live-quoted |
| Affiliate | Barcode To SKU | `x402-zeroclick-affiliate-com-v1-tools-convert-barcode-to-sku/call` | live-quoted |
| Affiliate | Merchants | `x402-zeroclick-affiliate-com-v1-merchants/call` | live-quoted |
| Affiliate | Products | `x402-zeroclick-affiliate-com-v1-products/call` | live-quoted |
| Affiliate | SKU To Barcode | `x402-zeroclick-affiliate-com-v1-tools-convert-sku-to-barcode/call` | live-quoted |
| Affiliate | URL To Barcode | `x402-zeroclick-affiliate-com-v1-tools-convert-url-to-barcode/call` | live-quoted |
| ARKM | Entity | `x402-api-arkm-com-x402-intelligence-entity/call` | live-quoted |
| ARKM | Entity Summary | `x402-api-arkm-com-x402-intelligence-entity-summary/call` | live-quoted |
| ARKM | Intelligence Address | `x402-api-arkm-com-x402-intelligence-address/call` | live-quoted |
| BIP-REP | DNS | `x402-tools-bip-rep-com-dns/call` | live-quoted |
| BIP-REP | Satellites | `x402-space-bip-rep-com-satellites/call` | live-quoted |
| Broken Key Remapper | Download Broken Key Remapper | `x402-brokenkey-api-link-tau-vercel-app-api-brokenkeyremapperlink/call` | live-quoted |
| Build With Locus | call | `mpp-buildwithlocus/call` | live-quoted |
| Cars 2026 | Cars | `x402-cars2026-vercel-app-api-cars/call` | live-quoted |
| Concierge Intelligence | Concierge Intel Whales | `x402-conc-exe-xyz-api-concierge-intel-whales/call` | live-quoted |
| Context.dev | call | `mpp-orth-context-dev/call` | live-quoted |
| Dappier | Real-time web search | `x402-dappier-real-time-search/call` | live-quoted |
| DeepAI | Background Remover | `x402-deepai-pay-zeroclick-io-api-background-remover/call` | live-quoted |
| DeepAI | Colorizer | `x402-deepai-pay-zeroclick-io-api-colorizer/call` | live-quoted |
| DeepAI | Creative Upscale | `x402-deepai-pay-zeroclick-io-api-creative-upscale/call` | live-quoted |
| DeepAI | Image Editor | `x402-deepai-pay-zeroclick-io-api-image-editor/call` | live-quoted |
| DeepAI | Text to Image | `x402-deepai-pay-zeroclick-io-api-text2img/call` | live-quoted |
| DeepAI | Torch SRGAN | `x402-deepai-pay-zeroclick-io-api-torch-srgan/call` | live-quoted |
| DemandEx | Trending | `x402-api-demandex-dev-v1-opportunities-trending/call` | live-quoted |
| Doma | call | `mpp-doma/call` | live-quoted |
| DripStack | call | `mpp-dripstack/call` | live-quoted |
| Fuchss | Trust | `x402-x402-fuchss-app-v1-x402-trust/call` | live-quoted |
| GitBeacon | Repos | `x402-api-gitbeacon-dev-v1-repos/call` | live-quoted |
| Hugen | All | `x402-tick-hugen-tokyo-tick-all/call` | live-quoted |
| Hugen | Latest | `x402-tick-hugen-tokyo-tick-latest/call` | live-quoted |
| InvokeT | Article Batch | `x402-api-invoket-com-legal-article-batch/call` | live-quoted |
| InvokeT | EU Act | `x402-api-invoket-com-legal-eu-act/call` | live-quoted |
| InvokeT | Repair | `x402-api-invoket-com-iban-repair/call` | live-quoted |
| InvokeT | Resolve | `x402-api-invoket-com-iban-resolve/call` | live-quoted |
| Kronos Signals | Options IV BTC | `x402-kronossignals-com-api-v1-options-iv-btc/call` | live-quoted |
| Life Advice | Life Advice | `x402-x402lifeadvice-vercel-app-api-life-advice/call` | live-quoted |
| LoyalSpark | Reward Status | `x402-api-loyalspark-online-x402-gateway-recipient-api-workflow-reward-status/call` | live-quoted |
| LoyalSpark | Vouchers | `x402-api-loyalspark-online-x402-gateway-recipient-api-vouchers/call` | live-quoted |
| Martin Estate Winery | call | `mpp-martin-estate/call` | live-quoted |
| Megapot | call | `mpp-megapot/call` | live-quoted |
| Modal | call | `mpp-modal/call` | live-quoted |
| NetIntel | Analyze | `x402-netintel-dev-asn-lookup-analyze/call` | live-quoted |
| NetIntel | Lookup | `x402-netintel-dev-dns-lookup/call` | live-quoted |
| Olostep API | call | `mpp-orth-olostep/call` | live-quoted |
| Oxylabs | call | `mpp-oxylabs/call` | live-quoted |
| Ozmium | Signals | `x402-ozmium-org-v1-signals/call` | live-quoted |
| PostalForm | call | `mpp-postalform/call` | live-quoted |
| Prospect Butcher | call | `mpp-prospect-butcher/call` | live-quoted |
| Regime Shift | VRP | `x402-regimeshift-xyz-api-v1-asset-btc-vrp/call` | live-quoted |
| Riveter API | call | `mpp-orth-riveter/call` | live-quoted |
| Run402 | Prototype | `x402-api-run402-com-tiers-v1-prototype/call` | live-quoted |
| Sayer & Stone | call | `mpp-sayer-and-stone/call` | live-quoted |
| ScrapeGraphAI | call | `mpp-orth-scrapegraphai/call` | live-quoted |
| Serper Scrape | call | `mpp-orth-serper-scrape/call` | live-quoted |
| SQLGuard | Cert | `x402-sqlguard-io-v1-cert/call` | live-quoted |
| SQLGuard | Session | `x402-sqlguard-io-v1-session/call` | live-quoted |
| Stripe Climate | call | `mpp-stripe-climate/call` | live-quoted |
| The Aslan Group | Carbon Intensity | `x402-gridpulse-theaslangroupllc-com-api-energy-carbon-intensity/call` | live-quoted |
| The Aslan Group | Quake Check | `x402-riskpulse-theaslangroupllc-com-api-risk-quake-check/call` | live-quoted |
| Transit | Nearest | `x402-transit402-dev-subway-nearest/call` | live-quoted |
| VAPE | Bridges | `x402-vape-x402-vapex402-workers-dev-data-bridges/call` | live-quoted |
| Vedetta | Feed | `x402-vedetta-dethboy-com-v1-feed/call` | live-quoted |
| Vedetta | Track Record | `x402-vedetta-dethboy-com-v1-track-record/call` | live-quoted |
| x402 Press | Ask | `x402-news-x402-press-news-ask/call` | live-quoted |
| x402 Stock | 4chan | `x402-agents-x402stock-xyz-api-v1-trending-4chan/call` | live-quoted |
| x402 Stock | Archive | `x402-agents-x402stock-xyz-api-v1-archive/call` | live-quoted |
| x402 Stock | Avg Interest Rates | `x402-agents-x402stock-xyz-api-v1-avg-interest-rates/call` | live-quoted |
| x402 Stock | Basis | `x402-agents-x402stock-xyz-api-v1-basis/call` | live-quoted |
| x402 Stock | Calendar | `x402-agents-x402stock-xyz-api-v1-calendar/call` | live-quoted |
| x402 Stock | Clinical Trials | `x402-agents-x402stock-xyz-api-v1-clinical-trials/call` | live-quoted |
| x402 Stock | Compare | `x402-agents-x402stock-xyz-api-v1-compare/call` | live-quoted |
| x402 Stock | Conditions | `x402-agents-x402stock-xyz-api-v1-conditions/call` | live-quoted |
| x402 Stock | Congress Trades | `x402-agents-x402stock-xyz-api-v1-congress-trades/call` | live-quoted |
| x402 Stock | COT | `x402-agents-x402stock-xyz-api-v1-cot/call` | live-quoted |
| x402 Stock | Crypto | `x402-agents-x402stock-xyz-api-v1-fear-greed-crypto/call` | live-quoted |
| x402 Stock | DEXs | `x402-agents-x402stock-xyz-api-v1-hip3-dexs/call` | live-quoted |
| x402 Stock | Dividend Calendar | `x402-agents-x402stock-xyz-api-v1-dividend-calendar/call` | live-quoted |
| x402 Stock | Energy | `x402-agents-x402stock-xyz-api-v1-energy/call` | live-quoted |
| x402 Stock | Exchange Rates | `x402-agents-x402stock-xyz-api-v1-exchange-rates/call` | live-quoted |
| x402 Stock | Exchanges | `x402-agents-x402stock-xyz-api-v1-exchanges/call` | live-quoted |
| x402 Stock | FDA | `x402-agents-x402stock-xyz-api-v1-fda/call` | live-quoted |
| x402 Stock | Fear Greed | `x402-agents-x402stock-xyz-api-v1-fear-greed/call` | live-quoted |
| x402 Stock | Fed Funds | `x402-agents-x402stock-xyz-api-v1-fed-funds/call` | live-quoted |
| x402 Stock | Filing Search | `x402-agents-x402stock-xyz-api-v1-filing-search/call` | live-quoted |
| x402 Stock | FOMC | `x402-agents-x402stock-xyz-api-v1-calendar-fomc/call` | live-quoted |
| x402 Stock | Form 144 | `x402-agents-x402stock-xyz-api-v1-form-144/call` | live-quoted |
| x402 Stock | Frames | `x402-agents-x402stock-xyz-api-v1-frames/call` | live-quoted |
| x402 Stock | GDP | `x402-agents-x402stock-xyz-api-v1-gdp/call` | live-quoted |
| x402 Stock | Gov Awards | `x402-agents-x402stock-xyz-api-v1-gov-awards/call` | live-quoted |
| x402 Stock | Gov Contracts | `x402-agents-x402stock-xyz-api-v1-gov-contracts/call` | live-quoted |
| x402 Stock | Grouped Daily | `x402-agents-x402stock-xyz-api-v1-grouped-daily/call` | live-quoted |
| x402 Stock | History | `x402-agents-x402stock-xyz-api-v1-fear-greed-history/call` | live-quoted |
| x402 Stock | Inflation | `x402-x402stock-xyz-api-v1-inflation/call` | live-quoted |
| x402 Stock | IPOs | `x402-agents-x402stock-xyz-api-v1-ipos/call` | live-quoted |
| x402 Stock | JLP | `x402-agents-x402stock-xyz-api-v1-solana-jlp/call` | live-quoted |
| x402 Stock | Labor Market | `x402-agents-x402stock-xyz-api-v1-labor-market/call` | live-quoted |
| x402 Stock | Liquidity | `x402-agents-x402stock-xyz-api-v1-fear-greed-liquidity/call` | live-quoted |
| x402 Stock | Macro | `x402-agents-x402stock-xyz-api-v1-macro/call` | live-quoted |
| x402 Stock | Market Pulse | `x402-agents-x402stock-xyz-api-v1-market-pulse/call` | live-quoted |
| x402 Stock | Money Supply | `x402-agents-x402stock-xyz-api-v1-money-supply/call` | live-quoted |
| x402 Stock | National Debt | `x402-agents-x402stock-xyz-api-v1-national-debt/call` | live-quoted |
| x402 Stock | News | `x402-x402stock-xyz-api-v1-news/call` | live-quoted |
| x402 Stock | News Sentiment | `x402-agents-x402stock-xyz-api-v1-news-sentiment/call` | live-quoted |
| x402 Stock | Patents | `x402-agents-x402stock-xyz-api-v1-patents/call` | live-quoted |
| x402 Stock | PCE | `x402-agents-x402stock-xyz-api-v1-pce/call` | live-quoted |
| x402 Stock | Perps | `x402-agents-x402stock-xyz-api-v1-perps/call` | live-quoted |
| x402 Stock | Portfolio X-Ray | `x402-agents-x402stock-xyz-api-v1-portfolio-xray/call` | live-quoted |
| x402 Stock | Predicted Funding | `x402-agents-x402stock-xyz-api-v1-perps-predicted-funding/call` | live-quoted |
| x402 Stock | Prediction Markets | `x402-agents-x402stock-xyz-api-v1-prediction-markets/call` | live-quoted |
| x402 Stock | Private Stocks | `x402-agents-x402stock-xyz-api-v1-private-stocks/call` | live-quoted |
| x402 Stock | Reddit | `x402-agents-x402stock-xyz-api-v1-trending-reddit/call` | live-quoted |
| x402 Stock | Regime | `x402-agents-x402stock-xyz-api-v1-fear-greed-regime/call` | live-quoted |
| x402 Stock | Regulatory | `x402-agents-x402stock-xyz-api-v1-regulatory/call` | live-quoted |
| x402 Stock | Shortages | `x402-agents-x402stock-xyz-api-v1-fda-shortages/call` | live-quoted |
| x402 Stock | Smart Screener | `x402-agents-x402stock-xyz-api-v1-screener-smart/call` | live-quoted |
| x402 Stock | Splits Calendar | `x402-agents-x402stock-xyz-api-v1-splits-calendar/call` | live-quoted |
| x402 Stock | Spot | `x402-agents-x402stock-xyz-api-v1-spot/call` | live-quoted |
| x402 Stock | Ticker Types | `x402-agents-x402stock-xyz-api-v1-ticker-types/call` | live-quoted |
| x402 Stock | Tickers | `x402-agents-x402stock-xyz-api-v1-tickers/call` | live-quoted |
| x402 Stock | Treasury Yields | `x402-x402stock-xyz-api-v1-treasury-yields/call` | live-quoted |
| x402 Stock | Trending | `x402-agents-x402stock-xyz-api-v1-trending/call` | live-quoted |
| x402 Stock | xStocks | `x402-agents-x402stock-xyz-api-v1-xstocks/call` | live-quoted |
| ZeroGPU | Chat completions | `x402-zerogpu-chat-completions/call` | live-quoted |
| ZeroGPU | Responses | `x402-zerogpu-responses/call` | live-quoted |
# Clean up integration tests
Source: https://docs.paywithlocus.com/locus-pro/clean-up-integration-tests
Retire live test users and reset policies while preserving transaction history.
Retire live test users when your integration tests are finished. This revokes their access while preserving the records needed to explain prior charges.
[Sandbox keys](/locus-pro/sandbox) create no live balances or end users and
need no cleanup.
## Prepare a test user for retirement
Stop issuing calls, tokens, and top-ups for the identity.
Let in-flight calls settle and hosted checkout sessions complete or expire.
Deallocate the balance to the workspace pool.
If retirement returns `409 END_USER_RETIREMENT_BLOCKED`, resolve the conditions listed in the response and retry.
## Retire the user
A workspace owner or admin with `tokens:manage` completes fresh MFA or passkey
verification, then calls:
```http title="Retire a test user" theme={null}
DELETE /api/credits/end-users/{externalUserId}
Authorization: Bearer
X-Locus-Step-Up:
```
Retirement leaves the identity inactive. Issuing a new token cannot
reactivate it. To reuse the identity, [reset its policy](#reset-a-policy-without-retiring-the-user) instead.
Retirement revokes tokens and Agent Connections, cancels cost approvals,
resets the active policy, and freezes the account.
Repeated retirement is safe. Financial and security history remain available.
## Reset a policy without retiring the user
Use this when the identity should remain available for another test:
```http title="Reset a policy" theme={null}
DELETE /api/credits/end-users/{externalUserId}/policy
Authorization: Bearer
```
The caller needs `tokens:manage`; dashboard callers must be an owner or admin. The reset waits until no active reservation depends on the policy and preserves its decision history.
The [API reference](/api-reference/introduction) covers permissions, blockers, and responses.
# Locus CLI
Source: https://docs.paywithlocus.com/locus-pro/cli
Find tools, inspect usage, and automate Locus Pro from your terminal.
The Locus CLI brings tool discovery, metered calls, and account management to your terminal. Use it interactively or give an agent structured JSON output for scripts and background jobs.
## Install and sign in
```bash title="Terminal" theme={null}
curl -fsSL https://paywithlocus.com/install/locus | sh
export PATH="${LOCUS_BIN_DIR:-${HOME}/.local/bin}:${PATH}"
```
The installer supports macOS and Linux, verifies the download, and installs
a matching agent skill. Add the install directory to your shell profile
for new shells. Run the installer again to upgrade.
```bash title="Terminal" theme={null}
locus auth login
locus auth status
```
Sign-in verifies your email through Okibi Identity. If that email has no
Locus account yet, Locus creates one with an agents workspace and emails
you a link to set a password. The CLI works right away. The dashboard
asks for that password first, so you can sign in there on your own.
The CLI credential expires 7 days after its last use and no later than
30 days after it was issued. Run `locus auth login` again to issue a
fresh one; a repeat sign-in replaces the credential for this
installation instead of failing.
## Find the command you need
Describe the job or browse help:
```bash title="Find a command" theme={null}
locus which "search the catalog"
locus catalog --help
```
Search enabled tools:
```bash title="Search tools" theme={null}
locus catalog search-enabled-executable-tools \
--query "company enrichment" \
--agent
```
The installed skill helps your agent choose commands and flags.
## Use it from an agent
`--agent` enables compact JSON output and non-interactive execution.
`--agent` also confirms writes. Add `--dry-run` to inspect a change first.
```bash title="Preview a change" theme={null}
locus tenants update-tenant-profile \
--name "Research workspace" \
--dry-run \
--agent
```
For an unattended enterprise agent, supply a scoped [Agent Connection](/locus-pro/connect-agents#enterprise-service-credentials) from your secret manager:
```bash title="Service credential" theme={null}
export LOCUS_SECRET_KEY="$LOCUS_AGENT_CONNECTION"
```
Keep tenant secret keys out of agent prompts. Reuse the same idempotency key when retrying a paid call or write whose outcome is uncertain.
## Commands and output
Available commands depend on your account and credential permissions.
| Command group | Use |
| ------------------ | ------------------------------------ |
| `catalog` | Find and manage tools |
| `credentials` | Create and verify credentials |
| `ledger` | Inspect credit activity |
| `top-ups` | Add funding |
| `end-users` | Manage customer balances |
| `tenants` | Manage enterprise workspace settings |
| `mcp` / `webhooks` | Configure integrations |
Use `--json` for structured output, `--csv` for tables, or `--select id,name,status` to choose fields. Each command's `--help` lists its options.
## Troubleshooting
```bash title="Check authentication and connectivity" theme={null}
locus auth doctor
locus doctor
```
These commands inspect authentication and connectivity without exposing the credential. If the default identity flow is unavailable, use `locus auth native`.
The CLI connects to `https://api.paywithlocus.com/api` by default.
## Next steps
* [Connect an agent](/locus-pro/connect-agents) to set tool and spend limits.
* [Enterprise quickstart](/locus-pro/enterprise/quickstart) to make your first metered API call.
# Commercial plans
Source: https://docs.paywithlocus.com/locus-pro/commercial-plans
Understand enterprise terms, evaluations, and how platform fees relate to tool usage.
Locus Pro Enterprise combines prepaid tool usage with the commercial terms agreed for your workspace.
Your signed Order Form determines pricing and commitments. Adding usage
credits changes your balance, not your contract or plan.
## Evaluate the product
An approved evaluation invitation includes **\$25 in non-refundable promotional credits**. Use them to test the hosted catalog at its normal prices.
You can add paid credits during an evaluation. Earnings payouts become available only after an active commercial agreement takes effect.
## Standard enterprise structure
Unless your Order Form specifies otherwise:
| Item | Standard terms |
| -------------------- | ---------------------------------------------------------------- |
| Pilot | 8 weeks for \$15,000, plus hosted API usage and processing costs |
| Production | 12 months with a \$60,000 annual commitment |
| Monthly platform fee | The greater of the \$5,000 minimum or the usage fee below |
| Payment terms | Net 30 |
The usage fee applies marginally to monthly provider-cost basis:
| Monthly provider-cost band | Rate |
| -------------------------- | ---: |
| First \$100,000 | 5% |
| Next \$400,000 | 4% |
| Above \$500,000 | 3% |
For example, \$500,000 of provider-cost basis produces a \$21,000 gross platform fee. The monthly minimum is included in that calculation rather than added to it.
## How this relates to catalog prices
Hosted tool calls continue to use the price returned by the catalog and draw from prepaid balances. Any Locus service component already included in those prices is credited against the month's gross platform fee, up to that fee.
Your customer markup, processing fees, taxes, and separately contracted add-ons are excluded from the usage-fee basis. Enterprise invoices are separate from prepaid customer balances.
## Recurring credit subscriptions
Some workspaces have a contracted monthly credit allowance. **Settings** shows its status, amount, and period end. The allowance is credited to the workspace pool as promotional credits.
Contact your Locus representative to change it. Card top-ups, auto-recharge, and the enterprise platform-fee commitment remain separate.
## Self-serve connection plans
Locus Pro includes one active OAuth-connected client at no monthly charge. Optional Plus and Unlimited plans increase active-client capacity:
| Plan | Monthly price | Active clients |
| --------- | ------------: | -------------: |
| Included | \$0 | 1 |
| Plus | \$20 | 3 |
| Unlimited | \$200 | Unlimited |
Tool credits are purchased separately. Connection plans do not limit simultaneous sessions or add enterprise features. Manage them from **Connections**; cancellation takes effect at the end of the billing period.
Fund usage and choose how customers pay.
Set your customer prices and understand margin.
# Connect an agent
Source: https://docs.paywithlocus.com/locus-pro/connect-agents
Give your agents paid tools, a shared balance, and clear spending limits through one MCP connection.
Connect your agent once to give it search, research, enrichment, and other paid tools from your Locus catalog. Locus handles provider access and billing; you choose the tools and spending limits.
| Your runtime | Connection |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| A coding or desktop client you use interactively | [OAuth](#interactive-oauth-recommended) |
| A hosted agent or background service | [Enterprise service credential](#enterprise-service-credentials) |
| An agent with its own account | [Agent-native onboarding](/locus-pro/agent-native-onboarding) |
Building with a model SDK? Go to [Framework integrations](/locus-pro/frameworks). For direct API calls, use the [Node SDK](/locus-pro/sdk).
See [MCP](/locus-pro/mcp) for the tool reference and compact mode.
## Connect an MCP client
The hosted MCP server uses Streamable HTTP:
```text title="MCP server URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp
```
### Interactive OAuth (recommended)
In your workspace, open **Integrate → MCP clients**. Add the MCP URL to your client and approve the connection in your browser. Locus Pro self-serve accounts use **Connections**.
Choose the manual configuration below or the [Locus plugin](#install-the-locus-plugin). You only need one connection.
Open **Customize → Connectors → Yours → Add connector → Add custom
connector**. Name it `Locus`, enter the MCP server URL above, choose
**Connect**, and complete browser sign-in.
Then open **Customize → Skills → Yours → Add skill → Upload skill** and
upload all three archives:
* [locus.zip](https://paywithlocus.com/.well-known/agent-skills/locus.zip)
* [locus-setup.zip](https://paywithlocus.com/.well-known/agent-skills/locus-setup.zip)
* [locus-workflows.zip](https://paywithlocus.com/.well-known/agent-skills/locus-workflows.zip)
This supplies the remote connector and complete skill tree to Claude
surfaces that expose these account settings. Claude Code uses its plugin
path below.
Enable Developer mode under **Settings → Apps → Advanced settings**,
then open **Plugins → Create app**. Enter the MCP server URL above, choose
OAuth, and finish Locus sign-in. Start a **Work** task, open **Plugins**,
and select **Locus Pro** before asking it to use a tool.
This custom-app path provides the MCP tools. ChatGPT's current Skills
picker may leave valid production archives ineligible. The MCP app still
works; use `get_locus_guide` for the same versioned operating guides when
the upload is unavailable.
```bash theme={null}
claude mcp add --transport http locus-pro \
https://api.paywithlocus.com/api/credits/mcp
```
Run `/mcp`, select `locus-pro`, and choose **Authenticate**.
```bash theme={null}
codex mcp add locus-pro --url https://api.paywithlocus.com/api/credits/mcp
codex mcp login locus-pro --scopes mcp:read,mcp:execute,offline_access
```
This direct configuration provides MCP tools only. Install the Codex
plugin below to add all three skills with the connection.
Add this to `~/.cursor/mcp.json`, enable the server, and follow the OAuth prompt:
```json title="~/.cursor/mcp.json" theme={null}
{
"mcpServers": {
"locus-pro": {
"url": "https://api.paywithlocus.com/api/credits/mcp"
}
}
}
```
```bash theme={null}
cline mcp install locus --transport http \
https://api.paywithlocus.com/api/credits/mcp
```
Choose **Remote (HTTP)** and **OAuth**, leave the client ID blank, and
complete browser sign-in. Then install all three skills and start a new
Cline session:
```bash theme={null}
npx skills add locus-technologies/locus-pro-plugin
```
Select `locus`, `locus-setup`, and `locus-workflows` when prompted.
Add the URL as a Streamable HTTP server without an authorization header.
Your client handles OAuth sign-in and token refresh.
### Install the Locus plugin
The [Locus plugin](https://github.com/locus-technologies/locus-pro-plugin)
bundles the OAuth connection with three skills: **Locus** for Tools and Recipes,
**Locus setup** for onboarding, and **Locus Workflows** for building and running
saved processes. Your client stores and refreshes the OAuth tokens.
```bash theme={null}
/plugin marketplace add locus-technologies/locus-pro-plugin
/plugin install locus@locus
```
Run `/mcp`, select `locus`, and choose **Authenticate**.
In Code, open **Customize → Plugins → Add plugin → Add marketplace → Add
from a repository**. Choose `locus-technologies/locus-pro-plugin`, select
**Sync**, then **Add Locus**.
Authenticate the plugin from Terminal:
```bash theme={null}
claude mcp login plugin:locus:locus
```
Complete browser consent, then start a new Code session. The plugin loads
`locus`, `locus-setup`, and `locus-workflows` with the MCP connection.
If the login command says `plugin:locus:locus` is missing and
`claude mcp get locus` reports a legacy **Local config**, remove the
project entry, restart Code, and retry:
```bash theme={null}
claude mcp remove locus -s local
```
```bash theme={null}
codex plugin marketplace add locus-technologies/locus-pro-plugin
codex plugin add locus@locus
codex mcp login locus --scopes mcp:read,mcp:execute,offline_access
```
Start a new CLI or desktop session after installation. The plugin loads
all three Locus skills with the MCP connection.
Review the plugin repository, then install:
```bash theme={null}
grok plugin install locus-technologies/locus-pro-plugin --trust
```
Grok opens browser sign-in when you first use the connection.
Use one OAuth entry per client. If you install the plugin after adding the server manually, remove the duplicate manual entry. For a service credential, use the [manual configuration](#enterprise-service-credential-configuration) below.
Other Agent Plugins clients can install the same bundle:
```bash title="Install the plugin" theme={null}
npx plugins add locus-technologies/locus-pro-plugin
```
Update through your client's plugin manager, then start a fresh session. See the
[release notes](https://github.com/locus-technologies/locus-pro-plugin/releases);
public marketplace listings may update separately from GitHub.
### One-link setup
For OpenClaw, Hermes, Muse, and Instinct, send this prompt in a new agent
session:
```text theme={null}
Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.
```
The installer chooses a supported MCP or CLI adapter, installs `locus`,
`locus-setup`, and `locus-workflows`, starts authentication, and checks a free
readiness operation. Complete any browser approval or restart it requests.
Hermes does not currently have a public plugin listing. Current OpenClaw
does not import the MCP entry from its marketplace bundle. Use the one-link
route for both clients today.
### Give your coding agent the Locus skills
Send your agent [paywithlocus.com/SKILL.md](https://paywithlocus.com/SKILL.md), or install the skills when you are not using the plugin:
```bash title="Install the skills" theme={null}
npx skills add locus-technologies/locus-pro-plugin
```
Select `locus`, `locus-setup`, and `locus-workflows` when prompted.
A skills-only install still
needs an authenticated MCP connection. Clients without local skill support can
retrieve the same guides through MCP with `get_locus_guide`.
## Enterprise service credentials
### What an agent connection is
An Agent Connection gives one runtime access to a chosen balance and set of tools. You can set an expiry, a maximum charge per call, and a spending limit per run.
Create it from **API Keys → Service credentials** or from your backend. Locus returns an `lcac_…` credential and ready-to-use MCP configuration.
Keep your `lcr_…` tenant secret key on your server. Give the agent a scoped
`lcac_…` credential. Store credentials in a secret manager, never in prompts
or source control.
### Create a connection
Your server key needs both `credentials:manage` and `credits:move` to create or
rotate a connection. Dashboard users must be an owner or admin and complete
recent MFA or passkey verification.
Enable the required endpoints in **Agent tools**. A connection can use
only enabled workspace tools.
```bash title="Create an Agent Connection" theme={null}
curl --fail-with-body -X POST "https://api.paywithlocus.com/api/credits/agent-connections" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "research-agent-prod",
"mode": "platform",
"tools": { "enable": ["tavily/search", "firecrawl/scrape"] },
"maxCreditsPerCall": "250",
"expiresInSeconds": 2592000
}'
```
Store the returned credential immediately. It is shown only on creation
and rotation.
| Setting | What you choose |
| -------------- | --------------------------------------------------------------------------- |
| Account | `platform` for your pooled balance, or `end_user` with one `externalUserId` |
| Tools | Exact `provider/endpoint` slugs the agent may call |
| Per-call limit | The largest charge one call may incur, in credits |
| Per-run limit | A shared credit budget for calls with the same loop ID |
| Expiry | How long the connection remains valid |
End-user connections can also carry their own pricing overrides. See the [API reference](/api-reference/introduction) for the full creation contract.
Omitting `tools` allows all workspace-enabled endpoints. An empty
`tools.enable` list permits none. Account and tool scope are fixed at
creation; create a replacement to change them.
### Enterprise service-credential configuration
Set `LOCUS_AGENT_CONNECTION` to the saved `lcac_…` credential.
Add to `~/.codex/config.toml`:
```toml title="~/.codex/config.toml" theme={null}
[mcp_servers.locus_pro]
url = "https://api.paywithlocus.com/api/credits/mcp"
bearer_token_env_var = "LOCUS_AGENT_CONNECTION"
```
```bash theme={null}
: "${LOCUS_AGENT_CONNECTION:?Set LOCUS_AGENT_CONNECTION first}"
claude mcp add --transport http locus-pro \
https://api.paywithlocus.com/api/credits/mcp \
--header "Authorization: Bearer $LOCUS_AGENT_CONNECTION"
```
Run `/mcp` to connect. Remove an existing `locus-pro` entry before replacing it.
Add to `.cursor/mcp.json` and keep this file out of source control:
```json title=".cursor/mcp.json" theme={null}
{
"mcpServers": {
"locus-pro": {
"url": "https://api.paywithlocus.com/api/credits/mcp",
"headers": {
"Authorization": "Bearer lcac_...your credential..."
}
}
}
}
```
Hosted model APIs have their own authorization fields. Use the examples in [Framework integrations](/locus-pro/frameworks).
### Connection scope and budgets
To enforce a run budget, set `maxCreditsPerLoop` at creation. Give every paid call in that run the same ID:
| Client | Where to pass it |
| ------------------ | -------------------------------------- |
| Node SDK | `{ loopId: "run_42" }` in call options |
| REST | `X-Locus-Agent-Loop-Id: run_42` |
| MCP `execute` | `loop_id: "run_42"` |
| Dedicated MCP tool | `_locus: { "loop_id": "run_42" }` |
Concurrent calls share the same budget. Start a new ID only for a new run.
## Use the MCP tools
Ask your agent to find the tool it needs, check the price, and use the result:
```text title="Send to your agent" wrap theme={null}
Find recent company news and funding information for this prospect.
Cite the sources and show what the research cost.
```
MCP exposes discovery and execution tools without loading the entire catalog.
See [all MCP tools](/locus-pro/mcp#all-tools) for the names and compact-mode equivalents.
When using a quote, pass its unchanged `approval_token`, arguments, and `idempotency_key` to `execute`. Dedicated endpoint tools cannot consume an approval token.
### Idempotency and replay
Reuse one `idempotency_key` when retrying a paid call. Locus returns the stored outcome without charging again. Use a new key for an intentional repeat, such as refreshing a search.
### Turn structured results into final answers
Store the paid result before asking the model to summarize it. If answer generation fails, reuse that result instead of repeating the purchase.
The SDK provides `parseMcpToolResult` to check tool errors, `prepareMcpResultForSynthesis` to build bounded context, and `selectSynthesisAnswer` for a fallback answer. The [Locus skill](https://paywithlocus.com/SKILL.md) covers the full runtime flow.
## Rotate or revoke a connection
Manage connections in **API Keys → Service credentials**, or use the SDK:
```typescript title="Rotate or revoke" theme={null}
const rotated = await locus.agentConnections.rotate(connectionId);
// Save rotated.credential; the old credential stops working immediately.
await locus.agentConnections.revoke(connectionId);
```
Rotation preserves scope. Revocation is immediate and permanent; a server key
needs only `credentials:manage` to revoke a connection.
## Troubleshoot a connection
| Problem | Check |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| `401` | Complete OAuth sign-in, or check that the service credential is set, active, and unexpired |
| Missing tools or `403` | Enable the endpoint in your workspace and include it in the connection's scope |
| `402` | Top up the account bound to the connection |
| Call or run limit exceeded | Use a cheaper tool or create a connection with a suitable budget |
| `AGENT_LOOP_ID_REQUIRED` | Pass the same loop ID on every call in the run |
| Client cannot initialize | Use the exact MCP URL and Streamable HTTP transport |
Share the connection ID and error code with support. Never share the full credential.
### Agent-owned headless OAuth
An agent-owned account signs in through AgentID. Keep the MCP login process alive while completing authorization so it retains its callback and PKCE state. Follow [Agent-native onboarding](/locus-pro/agent-native-onboarding) and the [AgentID authentication reference](https://paywithlocus.com/agent/auth.md) for the HTTP flow.
### Headless device authorization (RFC 8628)
Clients without a redirect listener can register for the device-code grant. They display a verification link, wait for approval, and exchange the device code for tokens. The [API reference](/api-reference/introduction) documents registration, polling intervals, and token renewal.
## Next steps
* [Framework integrations](/locus-pro/frameworks): connect your model SDK or agent framework.
* [SDK reference](/locus-pro/sdk): make direct calls and manage connections.
* [Locus CLI](/locus-pro/cli): work from a terminal.
# Credits and pricing
Source: https://docs.paywithlocus.com/locus-pro/credits-and-pricing
Pay for tools from one balance and set your own usage prices for customers.
Locus Pro Enterprise gives you one prepaid balance for tool usage and lets you set customer prices on top of each tool's base cost.
Use the workspace pool when you cover usage yourself. Charge an end-user balance when customers pay for their own usage. Your dashboard shows prices and balances in both credits and dollars.
## Choose who pays
| | Workspace pool | End-user balance |
| ------------- | ------------------------------------ | ----------------------------- |
| Best for | Internal agents and usage you absorb | Usage-based customer features |
| Price charged | Locus base price | Base price plus your markup |
| Margin | None | Your configured markup |
| Request | No end-user ID | Include `X-Locus-End-User` |
Self-serve Locus Pro accounts pay the listed tool price and do not configure resale pricing. See [Account and usage](/locus-pro/individual/account-and-usage).
## Set your markup
Add a percentage, a flat fee per call, or both. For example, a call with a \$0.05 base price and 20% markup costs your customer \$0.06 and earns \$0.01 in margin.
| Setting | API field | Example |
| -------------------- | ---------------- | ------------------- |
| Percentage markup | `markupBps` | `2000` = 20% |
| Flat markup per call | `flatMarkupUsdc` | `"0.002"` = \$0.002 |
### Global default, per-endpoint overrides
Set a workspace default, then override it for a provider or endpoint. Each pricing field uses the most specific configured value:
```text theme={null}
Endpoint → Provider → Workspace default
```
Review the resulting price in **Agent tools** or the [live catalog](/locus-pro/catalog#enterprise-read-the-live-catalog) before exposing the tool to customers.
### Worked examples
| Base cost | Markup | Customer price | Margin |
| --------: | ------------------ | -------------: | ------: |
| \$0.05 | 20% | \$0.06 | \$0.01 |
| \$0.01 | \$0.005 flat | \$0.015 | \$0.005 |
| \$0.05 | 20% + \$0.002 flat | \$0.062 | \$0.012 |
Prices are calculated with exact decimals and rounded up to six decimal places at the final step. Default markup caps are 100% and \$100 flat per call; contact support if your workspace needs different limits.
## Credit denomination
Credits express dollars in units that fit your product. The default is **1,000 credits = \$1**, so a \$0.0039 call costs 3.9 credits.
An enterprise workspace chooses its credits-per-dollar ratio during setup. That ratio is fixed afterward. Changing the denomination changes how prices are displayed, not their dollar value.
## How you receive margin
| How customers paid | Where the margin goes |
| --------------------------------------------- | ----------------------------------------------------------------------------------- |
| Your billing, followed by a credit allocation | The markup returns to your pool as credits are used; you already collected the cash |
| Locus-hosted checkout | Eligible markup accrues as payable earnings |
See [Earnings and payouts](/locus-pro/funding-and-billing#enterprise-earnings-and-payouts) for the holdback period and payout options.
## How calls are billed
### Response-priced endpoints
Some tools reserve a maximum before running, then charge for the usage measured in the response and release the rest. Markup applies to the measured base.
The final charge appears in the receipt and ledger. If a response is delivered but its usage cannot be recorded, the authorized maximum can remain charged.
### Live-priced endpoints
Some external services quote at call time. Inspect the quote and pass a hard `max_charge_credits` ceiling. Locus rejects a higher quote before dispatch without charging. See [Live-quoted endpoints](/locus-pro/catalog#live-quoted-endpoints).
### Failed calls and retries
A non-streaming call reserves credits and captures them when the provider returns success. An error or timeout before success releases the reservation.
Streaming calls capture after the provider accepts the stream. A later disconnect or stream failure remains charged. See [Inference and streaming](/locus-pro/inference#dynamic-charges-and-streaming).
Reuse the same `Idempotency-Key` when retrying the same logical call to avoid a second charge. If the balance is insufficient, the call returns `402` before execution.
## Keep your costs private
End-user tokens and the billing widget show the final customer price. Your base cost and margin remain available only to trusted management callers.
Fund balances and choose how customers pay.
Understand how enterprise fees relate to tool usage.
# Custom APIs
Source: https://docs.paywithlocus.com/locus-pro/custom-apis
Make your own HTTP services available to agents through Locus discovery, access controls, and billing.
Add your own service to Locus so agents can discover and call it alongside the hosted catalog. Custom APIs use the same access controls, activity history, and customer billing as other tools.
For example, expose an inventory lookup as `custom-inventory/check-stock` so a connected agent can check availability before recommending an item.
Custom APIs must be enabled for your enterprise workspace. They use your provider account and credential, so that provider's usage and data-handling terms still apply.
Creating or changing providers and actions requires a workspace owner with
recent MFA or passkey verification and the `catalog:write` and
`credentials:manage` scopes.
## Add a provider
Open **Agent tools → Custom APIs** and enter:
* A name, stable slug, description, and public HTTPS base URL.
* The authentication method: bearer token, custom header, query parameter, or none.
* Any rate, concurrency, or timeout limits your service needs.
Saved credentials stay private. The base URL must not contain credentials, query parameters, or a fragment.
## Add actions
Create an action manually or import an OpenAPI 3.0 or 3.1 JSON or YAML document. Supported actions use `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` with JSON-shaped inputs.
For each action, review the path, input schema, example, provider cost, and customer markup. New actions start disabled; enable them after review.
OpenAPI import explains any unsupported operations. You can select up to 50 compatible actions per save from a document containing up to 250 operations.
## Set pricing
Set a provider cost for each action, then optionally add percentage or flat markup for customers.
| Call mode | Billing |
| ---------------- | -------------------------------------------------------------------------------- |
| Workspace pool | No Locus credits consumed; your provider bills your saved credential directly |
| End-user balance | Configured provider cost plus markup; the full charge is workspace-owned revenue |
Both modes produce receipts and activity records.
## Let agents use the action
Enabled actions appear in the catalog and MCP discovery. Agents use the returned slug like any other tool. Servers can call the standard route:
```bash theme={null}
curl --fail-with-body -X POST \
"https://api.paywithlocus.com/api/wrapped/credits/custom-inventory/check-stock" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Idempotency-Key: inventory-check-SKU-1042-1" \
-H "Content-Type: application/json" \
-d '{"sku":"SKU-1042"}'
```
Reuse the idempotency key for retries. If an action changes data and times out, check the upstream state before starting a new request: the provider may have completed it.
## Manage access
Disable an action to stop future discovery and execution. Deleting a provider removes its actions and credential from future use; existing receipts and activity remain.
See the [API reference](/api-reference/introduction) for schema limits, import formats, and traffic controls.
Give an agent scoped access to your enabled actions.
Track who called your service and what it cost.
# Locus Pro Enterprise
Source: https://docs.paywithlocus.com/locus-pro/enterprise/overview
Ship agents with paid data, controlled spending, and usage-based billing through one integration.
Give your agents the APIs they need without building a separate integration and billing system for every provider. Locus Pro Enterprise puts search, research, enrichment, inference, and other paid tools behind one catalog and one prepaid balance.
Use it to run agents inside your company or power a product your customers pay to use. You choose the tools, control spending, and see what each call costs. Locus manages provider access and per-call settlement.
[Make your first call](/locus-pro/enterprise/quickstart) or [connect an agent](/locus-pro/connect-agents).
## Put better data in your product
A research assistant needs current sources. A sales agent needs verified company and contact data. A travel assistant needs live flight options. Locus gives these agents access to paid data as they need it, without separate provider subscriptions or credentials.
| Start with | When you need |
| ------------------------------------------- | --------------------------------------------------------------------- |
| [Tool](/locus-pro/catalog) | A particular provider or operation |
| [Recipe](/locus-pro/enterprise/recipes) | A complete outcome, such as a cited answer or enriched company record |
| [Workflow](/locus-pro/enterprise/workflows) | Your own repeatable process with consistent rules and a run budget |
## Turn agent usage into revenue
Give each customer a balance, set your prices, and charge for the tools they use. The [billing widget](/locus-pro/widget) adds balance display, transaction history, and top-ups to your app. You can also keep your existing billing and allocate credits after customers pay you.
For example, a prospecting product can charge for each enriched lead. You set a markup over the provider cost, attribute the call to the customer, and track usage and margin in the dashboard.
## Control access and spending
Use scoped Agent Connections for unattended agents and server keys for trusted integrations. Limit which tools an agent can call, set per-call or run budgets, and apply a workspace monthly cap.
Team roles separate development, billing, and administration. **Activity** lets you trace a charge to a user, agent, provider, or endpoint. **Analytics** shows usage and margin over time.
## Choose a call mode
| | Workspace pool | End-user balance |
| --------------- | ----------------------------------------------- | -------------------------------------------- |
| Best for | Internal agents, batch jobs, flat-rate products | Usage-based customer features |
| Balance charged | Your wholesale pool | The customer's balance |
| Price | Locus base price | Your price, including markup |
| Funding | Workspace top-up or auto-recharge | Customer top-up or allocation from your pool |
Both modes use the same catalog and API. You can start with pooled calls and add end-user billing as your product grows.
## Build on the same foundation
* **Custom APIs** bring your own HTTP services into agent discovery, access controls, and billing.
* **Recipes** combine providers into maintained search, research, extraction, enrichment, and travel outcomes.
* **Workflows** run your saved processes with versioned logic, spending limits, and results you can inspect.
* **Sandbox keys** let you test request handling without spending credits or calling providers.
## Get started
Create a key, enable a tool, and make a metered server call.
Connect an interactive client or give an unattended agent scoped access.
Choose how customers fund usage and how you earn margin.
Add complete data outcomes to your product with one call.
# Enterprise quickstart
Source: https://docs.paywithlocus.com/locus-pro/enterprise/quickstart
Enable a tool and make your first paid API call from your server.
Make a search request through Locus and charge it to your workspace pool. You'll need an enterprise workspace and owner or admin access to create the key.
If you are connecting an agent, use the [agent connection guide](/locus-pro/connect-agents) for OAuth or a scoped service credential.
Accept your evaluation or team invitation, sign in to the
[dashboard](https://platform.paywithlocus.com), and select the enterprise
workspace.
Open **API Keys** and create a secret key with `credits:move` for metered
calls. Complete MFA or passkey verification when prompted. Save the
returned value in your server's secret manager; it is shown once.
```bash theme={null}
export LOCUS_SECRET_KEY="lcr_..."
```
Keep this key on your server. Use OAuth for interactive agents and scoped
Agent Connections for unattended agents.
Open **Funding & billing → Funding** and add credits if needed. An
evaluation workspace may already have a promotional balance.
Open **Agent tools**, find `tavily/search`, review its price, and enable it.
```bash theme={null}
curl --fail-with-body -i -X POST \
https://api.paywithlocus.com/api/wrapped/credits/tavily/search \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Idempotency-Key: enterprise-quickstart-search-1" \
-H "Content-Type: application/json" \
-d '{"query":"recent primary-source announcements about coding agents"}'
```
The body contains the search result. Response headers show the charged
credits and remaining balance. Open **Activity** to find the call and
its cost.
Reuse the same idempotency key when retrying this request. Choose a new key
for a new search.
If the call fails, the response explains whether you need to enable the tool, add credits, or update access.
## Add customer billing
When you want customers to pay for their own usage, create end-user balances and set your markup. The [billing widget](/locus-pro/widget) adds balances and top-ups to your app using browser-safe credentials issued by your server.
Configure customer balances, auto-recharge, and spending caps.
Get complete research and enrichment outcomes through one call.
Make calls from Node or TypeScript.
# Recipes
Source: https://docs.paywithlocus.com/locus-pro/enterprise/recipes
Add research, enrichment, extraction, and flight comparison to your product with one call per outcome.
Recipes give your product complete data outcomes through one call. Locus handles provider selection, fallbacks, and merging results, so your team can build the feature around a consistent response.
Open **Agent tools → Recipes** to see what your workspace can use. Each Recipe describes its inputs, results, and pricing. Your agents can find those details through their connection.
## Choose the outcome
| Recipe | Input and result |
| -------------- | -------------------------------------------------------------------------------------------------------------- |
| Web Research | A question and effort level become a cited answer with completion status and cost |
| Web Search | A query and optional filters return ranked, deduplicated links with provider attribution |
| Web Extract | One to 20 public URLs and an optional focus return page content, freshness, and sources |
| GTM Enrichment | A person or company identifier and requested fields return a merged record with sources for each field |
| Locus Travel | Airports, dates, travelers, and preferences return ranked itineraries, booking availability, sources, and cost |
### Enrich a lead before writing outreach
Give GTM Enrichment a company domain or a prospect's LinkedIn URL and specify the fields your product needs. The Recipe fills gaps across compatible providers and returns the sources behind the record. Your agent can then write a briefing or draft outreach from those facts.
```text title="Try GTM Enrichment" wrap theme={null}
Enrich this prospect from their LinkedIn URL. Return their current role, company, location, and verified work email, with a source for each field. Use no more than 300 credits.
```
### Add current research to an assistant
Web Research returns an answer grounded in sources. Web Search returns links for your own agent to analyze. If the user supplies specific pages, Web Extract reads those URLs.
```text title="Try Web Research" wrap theme={null}
Compare the current pricing and enterprise features of these three products. Cite the vendor's page for each claim and flag anything you cannot verify.
```
### Compare live travel options
Locus Travel normalizes flight results across providers so your product can compare price, schedule, and preferences. Results include source confidence and whether an offer has a booking path; a returned itinerary is not a reservation.
## Enable and run a Recipe
Open it in **Agent tools → Recipes** and review its inputs and price behavior.
Enable it where a switch is available. Some built-in routes are system-managed.
Include it in the agent's allowed tools; a scoped Agent Connection needs
permission from both the workspace and its connection.
Let the agent check the inputs and price, then run it with the supported
spending ceiling.
For server integrations, the [routing guide](/locus-pro/capability-routing) shows a preview and execution example. The [API reference](/api-reference/introduction) has request schemas.
## Know what you are paying for
Recipes report exact charges and provider sources. Cost depends on the work performed; broader searches or more complete records can require more provider calls. Use a hard credit ceiling where the Recipe supports one.
A result can be partial when some providers succeed and others fail.
Successful work can still be charged. Inspect the returned status and
receipt before deciding whether to request more work.
## Reuse Recipes in Workflows
Recipes are maintained by Locus. [Workflows](/locus-pro/enterprise/workflows) save your team's process around them: enrich a list, apply qualification rules, deduplicate records, and produce a report under one run budget.
# Workflows
Source: https://docs.paywithlocus.com/locus-pro/enterprise/workflows
Save a repeatable process, run it on new inputs, and track its results and cost.
Workflows turn an agent's multi-step task into a process your team can reuse. Save the logic once, then run it on new inputs with a fixed version and spending ceiling.
A Workflow can call approved Tools and Recipes, apply your business rules, and produce results such as a qualified prospect list or a research report. Locus hosts the execution and records progress, tool calls, outputs, and charges.
## What to build
* **Lead qualification:** enrich company domains, remove duplicates, apply your ideal-customer criteria, and export the matching records.
* **Competitive research:** collect current sources for a list of companies and produce a consistent comparison.
* **Data processing:** extract content from supplied URLs, validate required fields, and flag records that need review.
Use a Recipe when one maintained outcome covers the task. Use a Workflow when you need your own sequence, rules, or output format.
## Build one with your agent
Connect a supported [agent client](/locus-pro/connect-agents) and describe the inputs, rules, output, and budget:
```text theme={null}
Create a Workflow that takes a list of company domains, enriches each company,
removes duplicates, and returns those with 50–500 employees. Include sources
and flag missing employee counts. Test it before saving, then pilot five
domains with a maximum budget of 1,000 credits.
```
The agent writes the process using approved Tools and Recipes, checks the
code, and tests sample inputs without calling providers.
Save the tested revision. Later edits do not change the version used by an
existing run.
Run a representative sample with a hard credit ceiling. Review the result
and cost before increasing the workload.
Run the saved version on new inputs. Open **Workflows** to inspect progress,
results, tool calls, errors, and charges.
Authoring and validation happen through the agent connection. The dashboard is where you monitor runs. Saving a Workflow does not schedule it or publish it.
## Control each run
| Control | What it does |
| ---------------- | ---------------------------------------------------------------------- |
| Saved version | Keeps production runs tied to fixed logic |
| Credit ceiling | Bounds each run's spending |
| Inherited access | Limits the run to the connection's account, allowed tools, and balance |
The Workflow cannot enable more tools or expand its own access.
You can cancel a run to stop new calls; completed work can remain charged. Some interrupted runs can resume from saved progress. Review their status and receipts in **Workflows** before resuming.
## How execution works
Workflows run versioned TypeScript in an isolated environment. Hosted code receives no account or provider credentials and can only call approved tools, with no arbitrary outbound requests.
Supported connections expose `workflow_definition`, `workflow_validate`, `workflow_run`, and `workflow_runs`. These tools let the agent create, test, save, run, and inspect Workflows. If they are absent, that connection does not currently support hosted Workflows.
Set up the connection that builds and runs your Workflow.
Use maintained outcomes as steps in your process.
# Framework integrations
Source: https://docs.paywithlocus.com/locus-pro/frameworks
Add Locus tools to the model SDK or agent framework you already use.
Give your application search, research, enrichment, and other paid tools through one MCP connection. Your framework discovers and calls the tools; Locus enforces access and spending limits.
These examples use a Locus Pro Enterprise [Agent Connection](/locus-pro/connect-agents#enterprise-service-credentials). For a desktop or coding client, use [interactive OAuth](/locus-pro/connect-agents#interactive-oauth-recommended).
## Choose an integration
| Framework | Available examples |
| ----------------------------------------- | --------------------------------------------- |
| [OpenAI](#openai) | Responses API, Agents SDK, managed Agents API |
| [Anthropic](#anthropic) | Messages API, Claude Agent SDK |
| [Vercel AI SDK](#vercel-ai-sdk) | TypeScript MCP client |
| [Google](#google-gen-ai-and-adk) | Gen AI Interactions API, ADK |
| [LangChain](#langchain) | Python and TypeScript |
| [LlamaIndex](#llamaindex) | Python and TypeScript |
| [CrewAI and AutoGen](#crewai-and-autogen) | Python |
| [Mastra](#mastra) | TypeScript |
| [Raw MCP](#raw-mcp-and-custom-frameworks) | Official clients and custom adapters |
## Connection values
[Create a connection](/locus-pro/connect-agents#create-a-connection) with the tools, account, expiry, and budget your agent needs.
```bash title="Runtime environment" theme={null}
export LOCUS_AGENT_CONNECTION="lcac_...your credential..."
export LOCUS_MCP_URL="https://api.paywithlocus.com/api/credits/mcp"
```
Store the credential in your runtime's secret manager. TypeScript presets use
the `connection` returned by the server SDK:
```typescript title="Trusted backend" theme={null}
import { LocusCredits } from "@withlocus/credits";
const locus = new LocusCredits(process.env.LOCUS_SECRET_KEY!);
const connection = await locus.agentConnections.create({
name: "research-agent-prod",
mode: "platform",
tools: { enable: ["tavily/search", "firecrawl/scrape"] },
maxCreditsPerCall: "250",
expiresIn: "30d",
});
```
Create it on your trusted backend. Give the runtime its scoped credential,
never the tenant secret key. Presets format each framework's authorization fields.
Keep the package pins shown in Python examples. Some adapters require MCP
1.x; the raw Python example uses MCP 2.x. If you add a per-run budget, pass
one `loop_id` across every paid call in that run.
## OpenAI
OpenAI can call Locus Pro as a hosted MCP tool. The Responses API and Agents SDK accept the raw `lcac_…` token; the managed Agents API uses a bearer header value.
These examples allow calls without per-call approval. Set tool and spending
limits on the connection before running them. For human approval, use
`require_approval: "always"` and handle the approval request in your application.
### Responses API
```typescript theme={null}
import OpenAI from "openai";
import { openAIResponsesMcpTool } from "@withlocus/credits";
const openai = new OpenAI();
const response = await openai.responses.create({
model: process.env.OPENAI_MODEL!,
input: "Research the requested topic and cite the sources you use.",
tools: [openAIResponsesMcpTool(connection)],
});
console.log(response.output_text);
```
```python theme={null}
import os
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model=os.environ["OPENAI_MODEL"],
input="Research the requested topic and cite the sources you use.",
tools=[{
"type": "mcp",
"server_label": "locus_pro",
"server_url": os.environ["LOCUS_MCP_URL"],
"authorization": os.environ["LOCUS_AGENT_CONNECTION"],
"require_approval": "never",
}],
)
print(response.output_text)
```
### Agents SDK
```typescript theme={null}
import { Agent, hostedMcpTool } from "@openai/agents";
import { openAIAgentsHostedMcpTool } from "@withlocus/credits";
const agent = new Agent({
name: "Locus research agent",
instructions: "Use only the approved Locus tools.",
tools: [hostedMcpTool(openAIAgentsHostedMcpTool(connection))],
});
```
```python theme={null}
import os
from agents import Agent, HostedMCPTool
agent = Agent(
name="Locus research agent",
instructions="Use only the approved Locus tools.",
tools=[
HostedMCPTool(tool_config={
"type": "mcp",
"server_label": "locus_pro",
"server_url": os.environ["LOCUS_MCP_URL"],
"authorization": os.environ["LOCUS_AGENT_CONNECTION"],
"require_approval": "never",
})
],
)
```
### Agents API (managed)
The managed Agents API connects directly to Locus using a service-origin MCP tool. Its `authorization` field takes the full `Bearer lcac_…` value. This raw configuration works without a Locus SDK preset.
```python theme={null}
import os
from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Use only the approved Locus tools.",
"tools": [{
"type": "mcp",
"server_label": "locus_pro",
"transport": {
"type": "http",
"server_url": os.environ["LOCUS_MCP_URL"],
"authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}",
},
"connection_origin": "service",
"required": True,
}],
},
environment={"type": "none"},
input="Check my Locus credit balance.",
)
# Poll until the session is idle, then read the answer:
# items = client.beta.agents.sessions.items.list(session.id)
```
### Approval and scope
OpenAI presets default to `requireApproval: "never"`. Set it to `"always"` if your application should ask before each call. The connection's Locus tool and spending limits apply in either case.
## Anthropic
Use Anthropic's hosted MCP connector when the Messages API should call Locus directly. Use the Claude Agent SDK HTTP transport when MCP should run in your application.
### Messages API
The hosted connector expects the raw `lcac_…` value in `authorization_token`.
```typescript theme={null}
import Anthropic from "@anthropic-ai/sdk";
import { anthropicMessagesMcp } from "@withlocus/credits";
const anthropic = new Anthropic();
const { server, toolset } = anthropicMessagesMcp(connection);
const response = await anthropic.beta.messages.create({
model: process.env.ANTHROPIC_MODEL!,
max_tokens: 2048,
betas: ["mcp-client-2025-11-20"],
mcp_servers: [server],
tools: [toolset],
messages: [{
role: "user",
content: "Search for the requested evidence and summarize it.",
}],
});
```
```python theme={null}
import os
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=2048,
betas=["mcp-client-2025-11-20"],
mcp_servers=[{
"type": "url",
"url": os.environ["LOCUS_MCP_URL"],
"name": "locus_pro",
"authorization_token": os.environ["LOCUS_AGENT_CONNECTION"],
}],
tools=[{
"type": "mcp_toolset",
"mcp_server_name": "locus_pro",
}],
messages=[{
"role": "user",
"content": "Search for the requested evidence and summarize it.",
}],
)
```
### Claude Agent SDK
The runtime transport expects the complete `Authorization` header:
```typescript theme={null}
import { query, type Options } from "@anthropic-ai/claude-agent-sdk";
import { claudeAgentSdkMcpServer } from "@withlocus/credits";
const options: Options = {
mcpServers: {
locus_pro: claudeAgentSdkMcpServer(connection),
},
strictMcpConfig: true,
};
for await (const message of query({
prompt: "Research the request with the approved Locus tools.",
options,
})) {
console.log(message);
}
```
```python theme={null}
import os
from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(
mcp_servers={
"locus_pro": {
"type": "http",
"url": os.environ["LOCUS_MCP_URL"],
"headers": {
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
}
},
)
```
Use `@anthropic-ai/claude-agent-sdk` 0.2.70 or later for the corrected Streamable HTTP `Accept` header behavior.
## Vercel AI SDK
Use `@ai-sdk/mcp` when your Vercel AI SDK agent should discover and execute Locus tools through Streamable HTTP.
```bash theme={null}
npm install ai @ai-sdk/mcp @withlocus/credits
```
### Create the MCP client
```typescript theme={null}
import { createMCPClient } from "@ai-sdk/mcp";
import { vercelAIMcpTransport } from "@withlocus/credits";
const mcp = await createMCPClient({
transport: vercelAIMcpTransport(connection),
});
try {
const tools = await mcp.tools();
// Pass `tools` to generateText(), streamText(), or an Agent.
} catch (error) {
console.error("Locus MCP connection failed", error);
throw error;
} finally {
await mcp.close();
}
```
Keep the MCP client open for the agent's lifetime and close it at shutdown.
### Tool results
Check `isError` when calling MCP directly, or use `parseMcpToolResult()`. [Store paid results before generating an answer](/locus-pro/connect-agents#turn-structured-results-into-final-answers) so an interrupted turn does not repeat the purchase.
## Google Gen AI and ADK
Google supports Locus Pro through two paths: hosted remote MCP in the Gen AI Interactions API, or a runtime `McpToolset` in Google ADK.
### Gen AI Interactions API
Remote MCP supports Streamable HTTP. Use a server name without hyphens; the Locus preset defaults to `locus_pro`.
```typescript theme={null}
import { GoogleGenAI } from "@google/genai";
import { googleGenAIMcpServer } from "@withlocus/credits";
const google = new GoogleGenAI({});
const interaction = await google.interactions.create({
model: process.env.GEMINI_MODEL!,
input: "Use the approved Locus tools to research this request.",
tools: [googleGenAIMcpServer(connection)],
});
console.log(interaction.output_text);
```
```python theme={null}
import os
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model=os.environ["GEMINI_MODEL"],
input="Use the approved Locus tools to research this request.",
tools=[{
"type": "mcp_server",
"name": "locus_pro",
"url": os.environ["LOCUS_MCP_URL"],
"headers": {
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
}],
)
print(interaction.output_text)
```
### Google ADK
```bash theme={null}
pip install "google-adk[mcp]"
```
The `[mcp]` extra installs the compatible MCP dependency.
```python theme={null}
import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import (
StreamableHTTPConnectionParams,
)
locus_tools = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url=os.environ["LOCUS_MCP_URL"],
headers={
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
)
)
agent = LlmAgent(
name="locus_research_agent",
model=os.environ["GEMINI_MODEL"],
instruction="Use only the approved Locus tools.",
tools=[locus_tools],
)
```
## LangChain
LangChain's MCP adapters discover Locus tools and expose them as normal LangChain tools. Use the same scoped connection in Python or TypeScript.
```typescript theme={null}
import { createAgent } from "langchain";
import { MultiServerMCPClient } from "@langchain/mcp-adapters";
import { langChainMcpServer } from "@withlocus/credits";
const mcp = new MultiServerMCPClient({
locus_pro: langChainMcpServer(connection),
});
const tools = await mcp.getTools();
const agent = createAgent({
model: process.env.LANGCHAIN_MODEL!,
tools,
});
const result = await agent.invoke({
messages: [{
role: "user",
content: "Research the requested topic with the approved tools.",
}],
});
console.log(result);
```
```bash theme={null}
pip install langchain langchain-mcp-adapters
```
```python theme={null}
import asyncio
import os
from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
async def main() -> None:
client = MultiServerMCPClient({
"locus_pro": {
"transport": "http",
"url": os.environ["LOCUS_MCP_URL"],
"headers": {
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
}
})
tools = await client.get_tools()
agent = create_agent(
model=os.environ["LANGCHAIN_MODEL"],
tools=tools,
)
result = await agent.ainvoke({
"messages": [{
"role": "user",
"content": "Research the requested topic with the approved tools.",
}]
})
print(result)
asyncio.run(main())
```
For `estimate_cost`, use the `{ provider, endpoint, body }` form for compatibility with older TypeScript adapters.
## LlamaIndex
Both LlamaIndex Python and LlamaIndexTS include MCP tool adapters. They convert Locus tool schemas into framework-native callable tools.
```bash title="Install the Python adapter" theme={null}
pip install "llama-index-tools-mcp<0.5" "mcp>=1.24,<2"
```
These pins keep the adapter on its compatible MCP 1.x dependency.
```python theme={null}
import os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
client = BasicMCPClient(
os.environ["LOCUS_MCP_URL"],
headers={
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
)
tool_spec = McpToolSpec(client=client)
tools = await tool_spec.to_tool_list_async()
# Pass `tools` to FunctionAgent or another LlamaIndex workflow.
```
```typescript theme={null}
import { mcp } from "@llamaindex/tools";
import { llamaIndexTSMcpServer } from "@withlocus/credits";
const server = mcp(llamaIndexTSMcpServer(connection));
try {
const tools = await server.tools();
// Pass `tools` to agent() from @llamaindex/workflow.
} catch (error) {
console.error("LlamaIndex could not load Locus tools", error);
throw error;
} finally {
await server.cleanup();
}
```
## CrewAI and AutoGen
CrewAI and AutoGen both accept authenticated Streamable HTTP MCP servers. Give each deployment its own Locus agent connection.
```bash title="Install CrewAI" theme={null}
pip install crewai
```
```python theme={null}
import os
from crewai import Agent
from crewai.mcp import MCPServerHTTP
researcher = Agent(
role="Research analyst",
goal="Find and synthesize evidence with approved APIs",
backstory="A careful analyst with a bounded tool and credit budget.",
mcps=[
MCPServerHTTP(
url=os.environ["LOCUS_MCP_URL"],
headers={
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
streamable=True,
cache_tools_list=True,
)
],
)
```
Refresh the worker's tool list after changing your workspace catalog.
```bash title="Install AutoGen" theme={null}
pip install "autogen-agentchat" "autogen-ext[openai,mcp]" "mcp>=1.24,<2"
```
Use `McpWorkbench` as a context manager to close the MCP session:
```python theme={null}
import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import (
McpWorkbench,
StreamableHttpServerParams,
)
async def main() -> None:
server = StreamableHttpServerParams(
url=os.environ["LOCUS_MCP_URL"],
headers={
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
},
)
model = OpenAIChatCompletionClient(model=os.environ["OPENAI_MODEL"])
async with McpWorkbench(server_params=server) as workbench:
agent = AssistantAgent(
"locus_research_agent",
model_client=model,
workbench=workbench,
reflect_on_tool_use=True,
)
result = await agent.run(
task="Research the request with the approved Locus tools."
)
print(result.messages[-1])
await model.close()
asyncio.run(main())
```
## Mastra
Mastra's `MCPClient` supports authenticated Streamable HTTP and converts MCP tools into Mastra tools.
```bash theme={null}
npm install @mastra/mcp @withlocus/credits
```
```typescript theme={null}
import { MCPClient } from "@mastra/mcp";
import { mastraMcpServer } from "@withlocus/credits";
const mcp = new MCPClient({
id: "locus-research-prod",
servers: {
locus_pro: mastraMcpServer(connection),
},
});
try {
const tools = await mcp.listTools();
// Pass `tools` to a Mastra Agent.
} catch (error) {
console.error("Mastra could not load Locus tools", error);
throw error;
} finally {
await mcp.disconnect();
}
```
## Raw MCP and custom frameworks
Use the official MCP clients when your runtime has no framework adapter. Locus uses Streamable HTTP and standard bearer authorization.
This example uses the stable `@modelcontextprotocol/sdk` package:
```typescript theme={null}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { mcpHttpConnection } from "@withlocus/credits";
const config = mcpHttpConnection(connection);
const client = new Client({ name: "locus-agent", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(new URL(config.url), {
requestInit: { headers: config.headers },
});
try {
await client.connect(transport);
const tools = await client.listTools();
console.log(tools.tools.map((tool) => tool.name));
} catch (error) {
console.error("Locus MCP request failed", error);
throw error;
} finally {
await client.close();
}
```
```bash title="Install the Python MCP client" theme={null}
pip install "mcp>=2" httpx
```
```python theme={null}
import asyncio
import os
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
async def main() -> None:
headers = {
"Authorization": f"Bearer {os.environ['LOCUS_AGENT_CONNECTION']}"
}
async with httpx.AsyncClient(headers=headers) as http:
async with streamable_http_client(
os.environ["LOCUS_MCP_URL"],
http_client=http,
) as (read_stream, write_stream):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tools = await session.list_tools()
print([tool.name for tool in tools.tools])
asyncio.run(main())
```
On MCP 2.x, read structured results from `result.structured_content`. Reuse the same idempotency key when retrying an uncertain paid call.
### Custom frameworks
A custom adapter needs four operations:
1. Connect with the MCP URL and authorization header.
2. Call `tools/list` and map each JSON Schema into the framework's tool type.
3. Route tool calls back to MCP `tools/call` without changing arguments.
4. Treat a resolved result with `isError: true` as a failed tool call.
Use `parseMcpToolResult()` when the adapter is written in TypeScript. It preserves Locus billing metadata, artifacts, retry guidance, and application errors.
### Pi
Pi requires a custom extension. Use the raw MCP or [REST API](/api-reference/introduction) path; Locus's Pi integration is experimental.
# Funding and billing
Source: https://docs.paywithlocus.com/locus-pro/funding-and-billing
Fund agent usage, let customers buy credits, and collect margin from your product.
Fund one workspace balance for your agents, or give customers their own balances and charge for usage at your prices. Locus handles top-ups, metering, and the transaction history.
## Choose a funding model
| Model | How it works | Best for |
| ---------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **You fund usage** | Top up the workspace pool; calls deduct the base price | Internal agents or usage included in your product price |
| **You bill customers** | Collect payment through your own billing, then allocate pool credits to customers | Products with an existing billing system |
| **Customers top up through Locus** | Embed the billing widget or send a hosted checkout link | Adding prepaid usage billing to your app |
For self-serve Locus Pro funding, see [Account and usage](/locus-pro/individual/account-and-usage).
## Fund your workspace
Open **Funding & billing → Funding**, choose an amount, and complete Stripe Checkout. The minimum top-up is **\$5**. Credits become available after payment is confirmed.
```bash theme={null}
curl --fail-with-body -X POST "https://api.paywithlocus.com/api/credits/topups" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Idempotency-Key: workspace-topup-1" \
-H "Content-Type: application/json" \
-d '{
"usd": "100.00",
"successUrl": "https://yourapp.com/billing?ok=1",
"cancelUrl": "https://yourapp.com/billing"
}'
```
Send the buyer to the returned `url`.
Confirm funding from the balance or a `credits.topup.completed` event.
A browser redirect alone does not confirm payment.
### Volume bonuses
Eligible enterprise pool top-ups include promotional credits. The default schedule is:
| Pool top-up | Bonus |
| ----------: | ----: |
| \$500 | 5% |
| \$1,000 | 10% |
| \$5,000 | 15% |
| \$10,000 | 20% |
Use `POST /api/credits/topups/quote` to get the current total, including any bonus and processing fee. Personal and end-user top-ups do not earn volume bonuses.
### Card processing fees
Choose whether buyers pay the processing fee separately or your workspace absorbs it. Display the returned quote so customers see the exact credits, fee, and total before paying.
### Auto-recharge
Complete one manual top-up to save a reusable payment method, then set a balance threshold and refill amount in the dashboard. Changes require a workspace owner or admin with recent MFA or passkey verification.
If the saved card fails, the dashboard alerts you. Calls can continue while enough credits remain.
## Set a spending ceiling
Set a monthly hard cap, a monthly-spend email threshold, and a low-balance email threshold. The monthly cap follows the UTC calendar month and counts completed charges plus funds reserved for calls in progress.
When a new call would exceed the cap, Locus rejects it before contacting the provider. Existing calls finish and settle normally. Raise the limit or wait for the next month to allow more spending.
An owner or admin must complete recent MFA or passkey verification to change these controls. An API key cannot raise its own spending ceiling.
## Fund customer balances
### Let customers buy credits
The [billing widget](/locus-pro/widget) shows a customer's balance and opens Locus-hosted Stripe Checkout. It uses a publishable key and a short-lived end-user token issued by your server.
You can also create a checkout link with `POST /api/credits/topups` by including the customer's `externalUserId`. Those credits belong to that customer and pay for calls at your configured price.
### Allocate credits after your own billing
If you already charge customers, move credits from your pool to their balance:
```bash theme={null}
curl --fail-with-body -X POST \
"https://api.paywithlocus.com/api/credits/end-users/user_123/allocate" \
-H "Authorization: Bearer $LOCUS_SECRET_KEY" \
-H "Idempotency-Key: allocate-user-123-1" \
-H "Content-Type: application/json" \
-d '{"credits":"5000"}'
```
Allocation moves existing credits; it does not charge a card. Use `deallocate` to return unused credits to the pool. When allocated credits are spent, the markup portion returns to your pool.
## Collect earnings
When customers buy credits through Locus-hosted checkout, your markup accrues as payable earnings as they use those credits. Margin matures after a holdback period, **30 days by default**, and eligible payouts are processed after review.
Open **Funding & billing → Payouts** to connect a Stripe account for bank payouts or set a USDC address on Base. The dashboard shows accrued and payable earnings. Payouts require an active commercial agreement; evaluation workspaces cannot receive them.
Payout-destination changes require an owner or admin through the dashboard with recent MFA or passkey verification. Changing a USDC address starts a 24-hour hold before the next payout.
If you collect customer payments yourself and allocate credits, you already hold the cash margin. That model does not create a Locus margin payout.
## Refunds and disputes
| Event | Result |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Non-streaming call fails before success | The credit reservation is released |
| Stream fails before provider acceptance | The reservation is released |
| Accepted stream later disconnects or fails | The call remains charged |
| Balance is insufficient | The call does not run or charge |
| Same request is retried with the same idempotency key | The original result is replayed without a second charge |
| Customer disputes a Locus-hosted top-up | Disputed credits are reclaimed and the account freezes; a favorable resolution reverses this |
Disputes on payments you collect through your own Stripe account remain under your billing policy.
## Follow payments with webhooks
Configure a webhook URL in the dashboard to receive top-up, charge, refund, balance, and dispute events. Use them to update your product after payment confirmation or notify a customer when their balance is low.
Verify each delivery's signature against the raw request body, reject stale timestamps, and deduplicate by event ID. The [API reference](/api-reference/introduction) and [signed fixtures](https://docs.paywithlocus.com/locus-pro/webhook-fixtures.json) cover verification and payloads.
## Review transactions
Open **Activity** to trace top-ups, charges, allocations, refunds, and payouts. Filter by customer, agent, provider, endpoint, or your own attribution fields.
For reporting, use `GET /api/credits/ledger` for entries and `GET /api/credits/ledger/summary` for totals. Financial history is append-only, so corrections remain visible as new entries.
Put balance display and top-ups in your app.
Choose your credit denomination and markup.
# Account, credits, and usage
Source: https://docs.paywithlocus.com/locus-pro/individual/account-and-usage
Add credits, control spending, and see what your agents cost.
Your agents share one prepaid balance. Open **Credits** to add funds and set
spending controls, or **Usage** to see what they spent.
## Credits and spending controls
Add credits by card through Stripe Checkout. At the default rate,
**1 credit = \$0.001**. New accounts start with a zero balance.
Under **Credits**, you can configure:
* **Auto-reload** to refill a low balance after your first card top-up, with a monthly reload limit.
* **Monthly spend cap** to block new spending when you reach your limit.
* **Low-balance alerts** to remind you before credits run out.
* **Payment history** to review your top-ups.
A spend cap stops new calls. Work already in progress or completed can still
be charged.
## Review usage
Open **Usage** and select 7, 30, or 90 days. See total spend, completed calls,
spending over time, and your most-used tools. The current day is included.
Use **Payment history** for money added and **Usage** for credits spent.
## Connect more agents
One active OAuth client is included. If you use several agent apps, an optional
plan adds more connections.
| Plan | Monthly price | Active clients |
| --------- | ------------: | -------------: |
| Included | \$0 | 1 |
| Plus | \$20 | 3 |
| Unlimited | \$200 | Unlimited |
These plans cover connections; tool calls still use your prepaid credits.
They limit connected clients, not the number of calls within a client.
Manage your plan and revoke unused clients under **Connections**. Canceling a
paid plan returns you to Included at the end of the billing period.
## Account security
Manage sign-in methods and passkeys under **Account security**. Review access
for your agent apps under **Connections**.
# Connect an agent
Source: https://docs.paywithlocus.com/locus-pro/individual/connect-agents
Install the Locus plugin or connect your agent through MCP.
Connect once to give your agent access to your enabled Locus tools. The
[quickstart](/locus-pro/individual/quickstart) lets your agent guide setup. For
manual setup, add this MCP server:
```text title="MCP server URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp
```
Use your client's browser sign-in flow and leave authorization headers empty.
The client manages authentication for you.
Choose either the plugin or manual setup below. You only need one connection.
See [MCP](/locus-pro/mcp) for the tool reference and compact mode.
## Install the Locus plugin
The [Locus plugin](https://github.com/locus-technologies/locus-pro-plugin)
adds the MCP connection and three skills:
* **Locus** helps your agent choose Tools and Recipes, check prices, and use results.
* **Locus setup** guides installation, sign-in, and account setup.
* **Locus Workflows** helps your agent build, test, save, and run repeatable processes.
Sign in through your client when prompted. You can create an account during
sign-in; the client stores and refreshes the connection's tokens.
```text title="Install in Claude Code CLI" wrap theme={null}
/plugin marketplace add locus-technologies/locus-pro-plugin
/plugin install locus@locus
```
Run `/mcp`, select `locus`, and choose **Authenticate**.
In Code, open **Customize → Plugins → Add plugin → Add marketplace → Add
from a repository**. Choose `locus-technologies/locus-pro-plugin`, select
**Sync**, then **Add Locus**.
Authenticate the plugin from Terminal:
```bash theme={null}
claude mcp login plugin:locus:locus
```
Complete browser consent, then start a new Code session. The plugin loads
`locus`, `locus-setup`, and `locus-workflows` with the MCP connection.
If the login command says `plugin:locus:locus` is missing and
`claude mcp get locus` reports a legacy **Local config**, remove the
project entry, restart Code, and retry:
```bash theme={null}
claude mcp remove locus -s local
```
```bash title="Install in Codex" theme={null}
codex plugin marketplace add locus-technologies/locus-pro-plugin
codex plugin add locus@locus
codex mcp login locus --scopes mcp:read,mcp:execute,offline_access
```
Start a new CLI or desktop session after installation. The plugin loads
all three Locus skills with the MCP connection.
Review the plugin repository, then install:
```bash title="Install in Grok" theme={null}
grok plugin install locus-technologies/locus-pro-plugin --trust
```
Grok opens browser sign-in when you first use the connection.
Already connected manually? Remove the duplicate manual entry when switching
to the plugin. One connection is enough.
## One-link setup
OpenClaw, Hermes, Muse, and Instinct can run the Locus installer directly.
Send the same prompt in a new agent session:
```text theme={null}
Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.
```
```text theme={null}
Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.
```
```text theme={null}
Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.
```
```text theme={null}
Install Locus Pro by following https://paywithlocus.com/SKILL.md. Use production.
```
The installer chooses a supported MCP or CLI adapter, installs `locus`,
`locus-setup`, and `locus-workflows`, starts authentication, and checks a free
readiness operation. Complete any browser approval or restart it requests.
Hermes does not currently have a public plugin listing. Current OpenClaw
does not import the MCP entry from its marketplace bundle. Use the one-link
route for both clients today.
## Configure the MCP server directly
Use this option if you haven't installed the plugin. Cursor and Cline can
connect directly this way.
Open **Customize → Connectors → Yours → Add connector → Add custom
connector**. Name it `Locus`, enter the MCP server URL above, choose
**Connect**, and complete browser sign-in.
Then open **Customize → Skills → Yours → Add skill → Upload skill** and
upload all three archives:
* [locus.zip](https://paywithlocus.com/.well-known/agent-skills/locus.zip)
* [locus-setup.zip](https://paywithlocus.com/.well-known/agent-skills/locus-setup.zip)
* [locus-workflows.zip](https://paywithlocus.com/.well-known/agent-skills/locus-workflows.zip)
This supplies the remote connector and complete skill tree to Claude
surfaces that expose these account settings. Claude Code uses its plugin
path above.
Enable Developer mode under **Settings → Apps → Advanced settings**,
then open **Plugins → Create app**. Enter the MCP server URL above, choose
OAuth, and finish Locus sign-in. Start a **Work** task, open **Plugins**,
and select **Locus Pro** before asking it to use a tool.
This custom-app path provides the MCP tools. ChatGPT's current Skills
picker may leave valid production archives ineligible. The MCP app still
works; use `get_locus_guide` for the same versioned operating guides when
the upload is unavailable.
```bash title="Connect Codex CLI" theme={null}
codex mcp add locus-pro --url https://api.paywithlocus.com/api/credits/mcp
codex mcp login locus-pro --scopes mcp:read,mcp:execute,offline_access
```
This direct configuration provides MCP tools only. Install the Codex
plugin above to add all three skills with the connection.
```bash title="Connect Claude Code" theme={null}
claude mcp add --transport http locus-pro \
https://api.paywithlocus.com/api/credits/mcp
```
Run `/mcp`, select `locus-pro`, and choose **Authenticate**.
Add this to `~/.cursor/mcp.json`, then complete browser sign-in:
```json title="~/.cursor/mcp.json" theme={null}
{
"mcpServers": {
"locus-pro": {
"url": "https://api.paywithlocus.com/api/credits/mcp"
}
}
}
```
```bash title="Connect Cline" theme={null}
cline mcp install locus --transport http \
https://api.paywithlocus.com/api/credits/mcp
```
Choose **Remote (HTTP)** and **OAuth**, leave the client ID blank, and
complete browser sign-in. Then install all three skills and start a new
Cline session:
```bash theme={null}
npx skills add locus-technologies/locus-pro-plugin
```
Select `locus`, `locus-setup`, and `locus-workflows` when prompted.
Add the server URL in your client's MCP settings. Choose Streamable HTTP
if it asks for a transport, then follow the sign-in prompt.
## Other plugin and skill clients
For a client that supports the Agent Plugins standard:
```bash title="Agent Plugins-compatible clients" theme={null}
npx plugins add locus-technologies/locus-pro-plugin
```
To install the three skills in an Agent Skills-compatible client:
```bash title="Install skills only" theme={null}
npx skills add locus-technologies/locus-pro-plugin
```
Select `locus`, `locus-setup`, and `locus-workflows` when prompted.
A skills-only install still needs the MCP connection above. If your client
cannot install skills, your agent can retrieve the same guides through MCP
using `get_locus_guide`.
## Keep the plugin up to date
Use your client's plugin manager to update Locus, then start a fresh session.
Keep an existing working connection when updating.
See the [plugin releases](https://github.com/locus-technologies/locus-pro-plugin/releases)
for changes. Public marketplace listings may update separately from the
GitHub version.
## Check the connection
Ask your agent to find a tool for a task. If it needs access, approve the
request or enable the tool under **Tools**.
Open **Connections** to review active clients. One client is included;
[connection plans](/locus-pro/individual/account-and-usage#connect-more-agents)
add capacity for more agent apps.
## Troubleshoot
| Problem | Next step |
| ------------------------ | --------------------------------------------------- |
| No Locus tools appear | Complete browser sign-in, then refresh the client |
| A tool is missing | Enable it under **Tools** and refresh the tool list |
| Authentication error | Authenticate again through the client |
| Insufficient credits | Add funds under **Credits** |
| Connection limit reached | Revoke an unused client or change your plan |
For an agent that owns its own account, see
[agent-native onboarding](/locus-pro/agent-native-onboarding).
# Locus Pro
Source: https://docs.paywithlocus.com/locus-pro/individual/overview
Give your agent on-demand access to proprietary data, paid APIs, and tools for real work.
Install Locus Pro and your agent can tap into company databases, website
technology records, verified contact data, property listings, financials, and
more, right in the conversation you're already having.
Locus connects agents like Claude Code and Codex to thousands of paid APIs
through **one connection and one prepaid balance**. You approve tool access
and fund the balance. Your agent finds the sources it needs, combines the
results, and reports what it spent.
[Connect your agent](/locus-pro/individual/quickstart), then try a task like these.
## Put better data to work
These are a few of the queries Locus Pro can unlock or materially improve by
giving your base agent the right data and tools at runtime.
### Find your next customers
Get a prospect sheet with the right companies, verified contacts where
available, and a specific reason for each pitch.
```text title="Try this prompt" wrap theme={null}
I'm launching a Klaviyo integration. Find 20 US brands using Shopify Plus and Klaviyo. Add company size, the head of ecommerce, and a work email where one can be found and verified. Read each brand's site and write one specific reason to reach out. Return a CSV with sources and flag any missing data. Show me an estimate before starting.
```
**Data behind it:** BuiltWith technology records, Apollo company and people
data, Hunter email discovery, ZeroBounce verification, and Firecrawl page
extraction.
Inspect the evidence behind a row, then ask your agent to refine the list.
### Compare rentals with local-market data
Bring rent estimates, nearby comparables, commute distances, and listing
details into one comparison.
```text title="Try this prompt" wrap theme={null}
Compare these five Austin rental listings. Pull the property records, nearby rental comparables, and rent estimates. Calculate the driving distance to my office and read the listings for parking and pet policies. Put everything in one table, link the sources, and label estimates.
```
**Data behind it:** RentCast property records, rental estimates, and
comparables; Mapbox routes and distances; Firecrawl listing-page extraction.
Ask follow-up questions from the same comparison, such as which listing has
the shortest commute or how its rent compares with nearby properties.
### Build an evidence-backed company brief
Compare financials, management commentary, and current reporting in a
spreadsheet and brief you can question, revise, or turn into a presentation.
```text title="Try this prompt" wrap theme={null}
Build a comparison of Microsoft, Salesforce, and Adobe. Pull their latest quarterly revenue, operating margin, and cash flow. Read the earnings-call transcripts for what management says about AI revenue, then check recent news. Return a spreadsheet and a one-page brief. Cite each figure and show the reporting period.
```
**Data behind it:** Alpha Vantage financial statements and earnings-call
transcripts, SEC EDGAR filing history and reported facts, Exa search, and
Firecrawl page extraction.
## One connection for a whole data stack
Those examples span **ten providers**. Connecting them separately means
choosing access plans, configuring credentials or payment methods, and giving
your agent a way to call each service.
With Locus, the tools share your connection and balance:
| What you need | With Locus Pro |
| ---------------------------------- | ---------------------------------------------------------- |
| Data from several providers | Your agent finds and calls them from one catalog |
| A tool for a one-off task | Pay for its calls from your existing balance |
| Several sources in one deliverable | Your agent combines their results in the same task |
| Control over spending | Review estimates, set limits, and see charges in **Usage** |
You don't need a separate provider subscription to use its tools through
Locus. Use a dataset for one question, then move on to the next task without
buying a plan for every source. Check the current quote before a large request.
One active agent connection is included. Optional
[connection plans](/locus-pro/individual/account-and-usage#connect-more-agents)
let you connect more agent apps.
## Start with your existing agent
Send your agent this link:
```text title="Send this link to your agent" wrap theme={null}
https://paywithlocus.com/SKILL.md
```
Or [install the Locus plugin](/locus-pro/individual/connect-agents#install-the-locus-plugin).
Sign in when prompted, approve the tools you need, and add credits. Then give
your agent the task, the output you want, and a spending limit.
## Make useful work repeatable
* **[Tools](/locus-pro/individual/tools):** Call a specific API for a lookup or action.
* **[Recipes](/locus-pro/individual/recipes):** Combine providers for research, enrichment, and other common outcomes.
* **[Workflows](/locus-pro/individual/workflows):** Save your own process to run on the next list with the same rules and budget.
Send one link to your agent to begin.
Get research, enrichment, and other complete outcomes.
Save a process you can run again.
Explore the tools your agent gets and choose a mode.
# Locus Pro quickstart
Source: https://docs.paywithlocus.com/locus-pro/individual/quickstart
Send one link to your agent. Create your account when it connects.
```text title="Copy this link" wrap theme={null}
https://paywithlocus.com/SKILL.md
```
**Send it to your agent.**
The skill guides your agent through setup and using Locus. You can create your
account during its first connection.
## Try a first prompt
Send the link along with a task:
```text title="Try this prompt" wrap theme={null}
Read https://paywithlocus.com/SKILL.md and use Locus to research alternatives to Linear for a ten-person engineering team. Compare current pricing and features, cite your sources, and recommend one.
```
## What happens next
Your agent starts the connection and opens a browser sign-in page. Sign in
or create an account, then approve access.
Your agent identifies suitable Tools or Recipes. Approve its access request
or enable them under **Tools** in the dashboard.
Accounts start with a zero balance. Open **Credits** and add funds by card
when you are ready to make paid calls.
Your agent runs the tools and returns the result with the exact charge.
Open **Usage** to review completed calls.
## If your client needs manual setup
Add this MCP server URL in your client's connection settings, then complete
browser sign-in. Leave authorization headers empty.
```text title="MCP server URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp
```
See [Connect an agent](/locus-pro/individual/connect-agents) for client-specific
instructions. Manage auto-reload, spending limits, and alerts under
[Account, credits, and usage](/locus-pro/individual/account-and-usage).
# Recipes
Source: https://docs.paywithlocus.com/locus-pro/individual/recipes
Get cited research, enriched records, and flight comparisons in one agent call.
Recipes handle tasks that would otherwise take several provider calls. Ask for
a result, and Locus chooses the providers, combines their responses, and returns
the result with sources and cost.
Use them from your connected agent. It can find the available Recipes and
request any tool access you need to approve.
## Choose a Recipe
| You need | Recipe |
| -------------------------------------------- | --------------------------------- |
| An answer backed by current sources | [Web Research](#web-research) |
| Relevant links for your agent to investigate | [Web Search](#web-search) |
| Content from pages you already have | [Web Extract](#web-extract) |
| A person or company record | [GTM Enrichment](#gtm-enrichment) |
| Comparable live flight options | [Locus Travel](#locus-travel) |
### Web Research
Get a current answer with citations. Give it your question, the depth of
research you want, and any required output format.
```text title="Try Web Research" wrap theme={null}
Compare the current pricing and features of Linear, Notion, and Jira for a 20-person software team. Cite the official pages and recommend one.
```
Choose light, medium, or heavy effort. Higher effort suits broader comparisons
and questions that need more cross-checking. The result includes an answer,
references, completion status, and cost.
### Web Search
Find sources across search engines. Locus combines and ranks the results,
removes duplicate URLs, and includes titles, excerpts, dates, and source
attribution.
```text title="Try Web Search" wrap theme={null}
Find official announcements from the last 30 days about new coding-agent models. Return the ten most relevant links with a short excerpt from each.
```
You can narrow the request by date, country, domains, and result count. Use it
when your agent will do the reading and analysis itself.
### Web Extract
Read one to 20 public URLs you supply. Locus extracts the page content and
tries another extractor for pages that fail, keeping the lookup limited to
your URLs.
```text title="Try Web Extract" wrap theme={null}
Read these three release-note URLs. Extract the breaking changes, migration steps, and version requirements into a table.
```
You can specify a focus, freshness limit, and maximum content length. Each
page's result identifies its source and whether the returned content was cut
short.
### GTM Enrichment
Turn an identifier into a person or company record. Locus fills the fields you
request across data providers and stops when the record is complete or reaches
your budget.
```text title="Try GTM Enrichment" wrap theme={null}
Enrich this prospect from their LinkedIn URL. Find their current role, company, location, and verified work email. Show the source for each field and spend no more than 300 credits.
```
Start with an email, LinkedIn URL, company domain, company name, or a person's
name and company. Discovered emails and phone numbers are verified by default.
The result includes field sources, verification evidence, and any missing
information. This Recipe requires a maximum credit charge.
### Locus Travel
Compare live flights in one request. Give it your airports, dates, travelers,
cabin, and preferences. Locus combines matching itineraries and ranks the
offers.
```text title="Try Locus Travel" wrap theme={null}
Find nonstop SFO to JFK flights next Thursday after 4 PM for one adult. Compare total price and arrival time, include available booking links, and spend no more than 500 credits.
```
You can filter by stops, schedule, airline, baggage, or price. Results include
source confidence and distinguish booking links from search links or
price-only offers. A flight search does not book a ticket.
## Cost and results
Recipes use your prepaid balance. The charge depends on which provider calls
run. Ask your agent for an estimate and a hard credit limit before a large
request.
Partial results can include paid work. Check missing sources or fields
before retrying; the returned charge and **Usage** show what you spent.
## Save your own process
Recipes are maintained by Locus. To apply your own rules repeatedly, build a
[Workflow](/locus-pro/individual/workflows) that uses Tools and Recipes. For a
specific provider or API operation, use a [Tool](/locus-pro/individual/tools).
# Tools
Source: https://docs.paywithlocus.com/locus-pro/individual/tools
Give your agent access to search, data, image generation, and other paid APIs.
Tools let your agent call individual APIs through your Locus balance. It can
generate an image, verify an email, retrieve a forecast, or look up company
data without a separate account or API key for each provider.
## Find a tool for your task
Ask your agent for the outcome you want. It can search the catalog and compare
available tools and prices.
```text title="Try this prompt" wrap theme={null}
Find an image-generation tool that supports a transparent background. Show me the available models and prices before I choose one.
```
Name a provider when you have a preference. Otherwise, let the agent find a
match. You can also browse the [API directory](/locus-pro/catalog-directory).
## Enable access
Open **Tools** in the dashboard and search for the provider or action.
Review what it does and what it costs.
Enable the actions you want your agent to use. Ordinary tools start disabled.
Your agent can also send you an access request to approve.
Ask it to complete the task. The result includes the charge and remaining
balance, and the call appears under **Usage**.
You can turn tools off at any time. An enabled tool may be temporarily paused
if its provider is unavailable. If your agent does not see a newly enabled
tool, refresh its tool list.
## Check the cost
Discovery and quotes are free. Paid executions use your prepaid balance.
For a large batch or variable-price request, ask your agent to quote the work
and set a maximum charge first. Manage your overall spending under
[Credits](/locus-pro/individual/account-and-usage).
## Use a Recipe for a complete task
[Recipes](/locus-pro/individual/recipes) combine providers for outcomes such as
cited research, company enrichment, or flight comparisons. Choose a direct
Tool when a particular provider or API operation matters.
# Workflows
Source: https://docs.paywithlocus.com/locus-pro/individual/workflows
Turn a task you repeat into a saved process with its own rules and budget.
Workflows let you save a process and run it again with new inputs. Your agent
builds it, Locus runs it, and you can review the results and cost in the dashboard.
Use a Workflow to qualify a list of companies, turn research into a consistent
report, or process new records using the same rules each time. It can combine
Tools and Recipes, filter results, and produce a file for you to use.
## Create your first Workflow
Ask your connected agent to build one:
```text title="Try this prompt" wrap theme={null}
Create a Workflow that takes a list of company domains, researches each company, and returns a CSV with industry, size, sources, and whether it fits our criteria: US software companies with 20 to 200 employees. Mark missing evidence as unknown. Test it on three companies with a 500-credit budget.
```
Include your input, desired output, decision rules, and spending limit. Your
agent handles the code and validation through your existing Locus connection.
## From draft to a repeatable run
Your agent creates the Workflow and tests its logic with sample data.
These checks do not call paid providers.
Save a version, then run a small pilot with a credit limit. Review the
output before processing the full list.
Use the saved version with new inputs and a budget. Later edits create a
new version, so you can keep using the process you tested.
## Review results and spending
Open **Workflows** to see run status, results, tool calls, errors, and credits
charged. Workflows use your existing balance and approved tools.
You can cancel a run to stop further calls. Completed work remains charged.
Your agent can inspect an interrupted run and resume it when supported.
Create and edit Workflows through your agent. Saving one does not schedule
it; start each run when you need it.
For a single research or enrichment task, try a
[Recipe](/locus-pro/individual/recipes). A Workflow adds your own rules and makes
the process reusable.
# Model inference
Source: https://docs.paywithlocus.com/locus-pro/inference
Pay for model calls from the same Locus balance you use for tools.
Run model inference and paid tools through one balance. Locus returns the cost of each model call alongside the remaining credits, so you can track the full cost of an agent task.
Enable the model endpoint in **Agent tools**. Use a scoped [Agent Connection](/locus-pro/connect-agents#enterprise-service-credentials) for a hosted runtime.
## Direct request
Locus Pro Enterprise accepts the provider's request body:
```bash title="Call a model" theme={null}
curl --fail-with-body --include \
--request POST \
--url https://api.paywithlocus.com/api/wrapped/credits/openai/chat \
--header "Authorization: Bearer $LOCUS_AGENT_CONNECTION" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: $(uuidgen)" \
--data '{
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": "Summarize this request."}],
"max_tokens": 120
}'
```
| Response header | Value |
| ------------------------- | ----------------- |
| `X-Locus-Credits-Charged` | Cost of this call |
| `X-Locus-Credits-Balance` | Remaining balance |
Reuse the original idempotency key when retrying a call with an uncertain outcome.
## Use an OpenAI-compatible client
```text title="OpenAI-compatible base URL" wrap theme={null}
https://api.paywithlocus.com/api/wrapped/credits/v1
```
Set the client's API key to your Locus credential.
Send a unique `Idempotency-Key` header and reuse it on retries.
`/chat/completions` accepts JSON and streaming requests.
## Agent and framework access
MCP clients can call enabled inference tools through their existing connection. Use [Framework integrations](/locus-pro/frameworks) for model SDKs and agent runtimes.
MCP supports non-streaming tool calls. Use REST when your application needs a streaming response. Locus Pro self-serve users enable inference under **Tools** and connect through [MCP OAuth](/locus-pro/individual/connect-agents).
## Dynamic charges and streaming
Locus quotes the model and request before dispatch. The charged amount is that quote, rather than a recalculation from final token usage.
| Request | When credits are charged |
| ------------- | -------------------------------------------------------------------- |
| Non-streaming | On success; an earlier failure releases the reservation |
| Streaming | When the provider accepts the stream, before the first response byte |
A later disconnection or stream failure does not reverse a streaming charge.
## Next steps
* [Tools and pricing](/locus-pro/catalog): choose endpoints and inspect prices.
* [Node SDK](/locus-pro/sdk): read costs and handle errors in your application.
# MCP
Source: https://docs.paywithlocus.com/locus-pro/mcp
Give your agent access to Locus tools, Recipes, and Workflows through one connection.
Locus MCP lets your agent find the right tool, check its price, and use it with
your Locus balance. It brings search, research, enrichment, and other paid APIs
into the agent you already use, without separate provider accounts.
MCP, the Model Context Protocol, is how an agent discovers and calls tools.
You describe the outcome; your agent uses Locus to get the data or complete
the task.
## Connect once
Add this Streamable HTTP server to your agent and complete browser sign-in:
```text title="MCP server URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp
```
The [Locus plugin](/locus-pro/individual/connect-agents#install-the-locus-plugin)
includes this connection plus skills for setup, tool use, and Workflows.
For client-specific instructions, see [Connect an agent](/locus-pro/individual/connect-agents).
Then try:
```text title="Try this prompt" wrap theme={null}
Use Locus to research three competitors for my project. Read their current pricing pages, compare their features, and link to the sources.
```
Your agent can discover tools, request your approval for disabled ones, and
read results back into the conversation. Paid calls use your credit balance.
Your tool permissions and spending limits still apply.
## Choose a mode
Both modes can use the same permitted catalog through `execute`. The difference
is how many tool definitions your agent loads and the names it sees.
* **Standard (default):** Descriptive tool names, available Recipes, and selected
or pinned endpoints. Use it to make Recipes and frequent tools directly accessible.
* **Compact:** Short discovery and execution names, account helpers, and available
Workflow tools. Use it to load fewer tool definitions into your agent's context.
The plugin and the plain MCP URL use standard mode. To choose compact mode,
change the URL in your client's MCP configuration to:
```text title="Compact mode URL" wrap theme={null}
https://api.paywithlocus.com/api/credits/mcp?surface=compact
```
Refresh the connection or start a new session after changing it. Keep one
connection per client; you do not need a second server entry.
`?surface=compact` reduces the tool list and removes whitespace from JSON
result text. `?compact=1` only changes result formatting. Both preserve the
structured result.
## How your agent uses Locus
1. **Find a tool.** Search by the outcome you need, or browse categories and packs.
2. **Check the inputs and price.** Read the endpoint description; request an exact
quote or hard spending ceiling when needed.
3. **Run it.** Call the enabled endpoint and use the returned data. Large results
can be read in chunks without repeating the paid call.
Search returns enabled tools by default. Your agent can include disabled tools
and request an approval link for one you need. You decide whether to enable it.
For repeatable work, your agent can build, test, save, and run a
[Workflow](/locus-pro/individual/workflows) through the same connection.
## All tools
The tables below cover Locus's built-in tools. Your client's live tool list
reflects your connection permissions, available features, and selected mode.
Provider-specific tools are discovered from the catalog as described below.
### Find and use tools
Where names differ, the compact name appears second.
| Tool (standard / compact) | Purpose |
| -------------------------------- | ------------------------------------------------------------ |
| `search_apis` / `search` | Find APIs and Recipes with prices, inputs, and access status |
| `describe_api` / `describe` | Read an endpoint's inputs, example, output format, and price |
| `estimate_cost` / `estimate` | Quote a call, optionally with a hard credit ceiling |
| `execute` | Call an enabled API or Recipe; paid calls charge credits |
| `get_call_result` / `get_result` | Read a stored result without rerunning the paid call |
| `list_tool_groups` | Browse categories and curated packs |
| `get_locus_guide` | Retrieve setup, usage, or Workflow guides |
| `request_tool_access` | Create a human approval link for a disabled tool |
| `get_balance` | Check the balance available to the connection |
### Workflows
These names are the same in both modes. Workflow authoring and execution
require an execution-enabled connection.
| Tool | Purpose |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `workflow_definition` | List, create, inspect, update, clone, archive, or save a Workflow |
| `workflow_validate` | Check source code or run isolated tests without network access |
| `workflow_run` | Start a pilot or production run of a saved version with a hard credit ceiling |
| `workflow_runs` | List runs, read status and stored results, cancel further calls, or resume an eligible run |
### Additional standard tools
| Tool | Purpose |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list_apis` | Browse a page of enabled endpoints and prices; omitted from the advertised list when more than 20 endpoints are available |
| `cancel_cost_approval` | Cancel an unused executable quote |
| `pin_endpoint` | Add or remove a saved endpoint pin when pinning is available; requires permission to manage pins |
These tools are not advertised in compact mode. Their original names remain
callable when your connection is permitted to use them.
### Direct Recipe tools
Standard mode also lists these [Recipes](/locus-pro/individual/recipes) when
they are available to your connection. In compact mode, find the Recipe with
`search`, then call its endpoint through `execute`.
| Tool | Purpose |
| ------------------- | ----------------------------------------------------- |
| `router_web_search` | Search the web across providers |
| `web_research` | Research a question and return a source-backed answer |
| `web_extract` | Extract content from specific URLs |
| `gtm_enrich` | Enrich a person or company with field-level sources |
| `travel_flights` | Search flights across providers |
Search returns the endpoint slug and inputs to use with `execute`.
### Provider-specific tools
Locus does not load the entire catalog as individual MCP tools. Your agent
discovers endpoints through search and calls them with `execute`.
In standard mode, you can expose frequently used endpoints as direct tools
with their own input schemas. Append `?tool=provider/endpoint` to the MCP URL,
using an exact slug returned by search. Repeat `tool` to select more, up to 20.
Saved pins can also expose endpoints across your workspace's connections.
Direct tool names usually follow `provider_endpoint`. Use the name returned
by Locus rather than constructing it yourself. Enabling or pinning a tool
does not override the connection's access or spending limits.
Browser OAuth is the usual connection for Locus Pro. Read-only consent
(`mcp:read`) allows discovery, balance checks, estimates, and stored-result
reads. Paid calls and Workflow operations require `mcp:execute`.
Locus Pro Enterprise also supports scoped Agent Connections, server keys,
and end-user tokens. End-user JWTs cannot use Workflows. Connections bound
to an end user cannot request workspace tool access. Sandbox keys cannot use MCP.
Saved pin changes require an owner or admin, or a server key with
`catalog:write`. The first pin requires acknowledgement that its schema
will use context on each connection.
See [Enterprise connection setup](/locus-pro/connect-agents#enterprise-service-credentials)
for credential configuration.
Clients that support MCP resources can read the catalog (`locus://catalog`),
balance (`locus://balance`), Recipe index (`locus://recipes`), and GTM guide
(`locus://recipes/gtm-enrich-record`). Resource templates provide catalog
pages and stored call results.
The server also offers `getting-started`, `find-and-call-api`, and
`enrich-gtm-record` prompts. Read-only connections receive the getting-started
prompt.
For detailed agent instructions, use the
[MCP reference](https://paywithlocus.com/agent/mcp.md) or ask your agent to call
`get_locus_guide`.
# Parse API directory
Source: https://docs.paywithlocus.com/locus-pro/parse-directory
All 3,290 Parse API listings and 15,204 endpoints available through Locus Pro, grouped by category.
Explore **3,290 Parse listings** with **15,204 API operations**, from public datasets and company records to travel and shopping. Choose a category below, or ask your agent to find an API for your task.
Parse operates these listings. Use the **Parse** source filter in the dashboard
to browse them, and inspect each API through your agent for its current inputs
and availability.
## Complete directory by category
| Category | Parse APIs | Endpoints |
| -------------------------------------------------------------- | ---------: | --------: |
| [Automotive](/locus-pro/parse/automotive) | 100 | 442 |
| [Business Directories](/locus-pro/parse/b2b-directory) | 133 | 529 |
| [Developer Tools](/locus-pro/parse/developer-tools) | 141 | 550 |
| [E-commerce](/locus-pro/parse/ecommerce) | 451 | 2,169 |
| [Education](/locus-pro/parse/education) | 150 | 777 |
| [Entertainment](/locus-pro/parse/entertainment) | 222 | 1,032 |
| [Finance & Markets](/locus-pro/parse/finance) | 245 | 1,285 |
| [Food & Dining](/locus-pro/parse/food-dining) | 157 | 691 |
| [Government & Public Data](/locus-pro/parse/government-public) | 311 | 1,380 |
| [Healthcare](/locus-pro/parse/healthcare) | 86 | 396 |
| [Jobs](/locus-pro/parse/jobs) | 103 | 401 |
| [Maps & Geospatial](/locus-pro/parse/maps-geo) | 46 | 221 |
| [Marketplaces](/locus-pro/parse/marketplace) | 238 | 1,114 |
| [Music](/locus-pro/parse/music) | 53 | 284 |
| [News & Media](/locus-pro/parse/news-media) | 57 | 283 |
| [Other](/locus-pro/parse/other) | 60 | 237 |
| [Real Estate](/locus-pro/parse/real-estate) | 172 | 638 |
| [Reviews & Ratings](/locus-pro/parse/reviews-ratings) | 24 | 129 |
| [Social Media](/locus-pro/parse/social-media) | 30 | 92 |
| [Sports](/locus-pro/parse/sports) | 278 | 1,481 |
| [Streaming Video](/locus-pro/parse/streaming-video) | 17 | 50 |
| [Travel](/locus-pro/parse/travel) | 132 | 512 |
| [Weather](/locus-pro/parse/weather) | 33 | 156 |
| [Web3 & Onchain](/locus-pro/parse/crypto-web3) | 51 | 355 |
## Parse marketplace order
Listings follow Parse marketplace rank within each category.
| Rank | API | Category | Endpoints |
| ---: | -------------------------------- | -------------------------------------------------------------- | --------: |
| 1 | NASA | [Government & Public Data](/locus-pro/parse/government-public) | 11 |
| 2 | Walmart | [E-commerce](/locus-pro/parse/ecommerce) | 6 |
| 3 | Zillow | [Real Estate](/locus-pro/parse/real-estate) | 8 |
| 4 | FRED | [Finance & Markets](/locus-pro/parse/finance) | 9 |
| 5 | IKEA | [E-commerce](/locus-pro/parse/ecommerce) | 10 |
| 6 | European Central Bank | [Finance & Markets](/locus-pro/parse/finance) | 3 |
| 7 | Maersk | [Maps & Geospatial](/locus-pro/parse/maps-geo) | 11 |
| 8 | Drugs.com | [Healthcare](/locus-pro/parse/healthcare) | 8 |
| 9 | eBay | [Marketplaces](/locus-pro/parse/marketplace) | 8 |
| 10 | CME Group | [Finance & Markets](/locus-pro/parse/finance) | 7 |
| 11 | OpenTable | [Food & Dining](/locus-pro/parse/food-dining) | 5 |
| 12 | Home Depot | [E-commerce](/locus-pro/parse/ecommerce) | 5 |
| 13 | National Weather Service | [Weather](/locus-pro/parse/weather) | 3 |
| 14 | Crunchbase | [Business Directories](/locus-pro/parse/b2b-directory) | 5 |
| 15 | USAJOBS | [Jobs](/locus-pro/parse/jobs) | 4 |
| 16 | USAspending | [Government & Public Data](/locus-pro/parse/government-public) | 6 |
| 17 | Lever Jobs | [Jobs](/locus-pro/parse/jobs) | 6 |
| 18 | Steam | [Entertainment](/locus-pro/parse/entertainment) | 4 |
| 20 | Transfermarkt | [Sports](/locus-pro/parse/sports) | 10 |
| 21 | Reserve Bank of Australia | [Finance & Markets](/locus-pro/parse/finance) | 8 |
| 22 | Resy | [Food & Dining](/locus-pro/parse/food-dining) | 5 |
| 23 | PubMed Central | [Healthcare](/locus-pro/parse/healthcare) | 6 |
| 24 | Dun & Bradstreet | [Business Directories](/locus-pro/parse/b2b-directory) | 3 |
| 25 | ClinicalTrials.gov | [Healthcare](/locus-pro/parse/healthcare) | 8 |
| 26 | NCBI | [Healthcare](/locus-pro/parse/healthcare) | 5 |
| 27 | Zoopla | [Real Estate](/locus-pro/parse/real-estate) | 5 |
| 28 | FDIC BankFind | [Finance & Markets](/locus-pro/parse/finance) | 11 |
| 30 | Companies House Developer | [Government & Public Data](/locus-pro/parse/government-public) | 3 |
| 31 | arXiv | [Education](/locus-pro/parse/education) | 3 |
| 32 | NIH PubMed | [Healthcare](/locus-pro/parse/healthcare) | 11 |
| 33 | Polygon | [Finance & Markets](/locus-pro/parse/finance) | 7 |
| 34 | Hacker News | [News & Media](/locus-pro/parse/news-media) | 9 |
| 35 | USDA FoodData Central | [Food & Dining](/locus-pro/parse/food-dining) | 6 |
| 36 | Companies House | [Government & Public Data](/locus-pro/parse/government-public) | 8 |
| 37 | Amazon UK | [E-commerce](/locus-pro/parse/ecommerce) | 4 |
| 38 | Etherscan | [Web3 & Onchain](/locus-pro/parse/crypto-web3) | 11 |
| 39 | Companies House Register | [Government & Public Data](/locus-pro/parse/government-public) | 7 |
| 40 | Funda | [Real Estate](/locus-pro/parse/real-estate) | 4 |
| 41 | Epic Games Store | [Entertainment](/locus-pro/parse/entertainment) | 12 |
| 42 | OpenDota | [Sports](/locus-pro/parse/sports) | 9 |
| 43 | Domain Australia | [Real Estate](/locus-pro/parse/real-estate) | 7 |
| 44 | NCBI BLAST | [Healthcare](/locus-pro/parse/healthcare) | 4 |
| 45 | NHL | [Sports](/locus-pro/parse/sports) | 9 |
| 46 | Kraken | [Web3 & Onchain](/locus-pro/parse/crypto-web3) | 6 |
| 47 | Trustpilot | [Reviews & Ratings](/locus-pro/parse/reviews-ratings) | 8 |
| 48 | Texas Legislature | [Government & Public Data](/locus-pro/parse/government-public) | 7 |
| 49 | Michelin Guide | [Food & Dining](/locus-pro/parse/food-dining) | 7 |
| 50 | NASA Mars | [Government & Public Data](/locus-pro/parse/government-public) | 12 |
| 51 | PSA Card | [Marketplaces](/locus-pro/parse/marketplace) | 9 |
| 52 | crt.sh | [Developer Tools](/locus-pro/parse/developer-tools) | 6 |
| 53 | AliExpress | [Marketplaces](/locus-pro/parse/marketplace) | 5 |
| 54 | Idealo | [E-commerce](/locus-pro/parse/ecommerce) | 6 |
| 55 | Mercado Libre | [Marketplaces](/locus-pro/parse/marketplace) | 5 |
| 56 | Indeed | [Jobs](/locus-pro/parse/jobs) | 5 |
| 57 | Polymarket | [Finance & Markets](/locus-pro/parse/finance) | 8 |
| 58 | Nike | [E-commerce](/locus-pro/parse/ecommerce) | 4 |
| 59 | LiveScore | [Sports](/locus-pro/parse/sports) | 12 |
| 60 | FantasyPros | [Sports](/locus-pro/parse/sports) | 7 |
| 61 | Indeed India | [Jobs](/locus-pro/parse/jobs) | 6 |
| 62 | Newegg | [E-commerce](/locus-pro/parse/ecommerce) | 7 |
| 63 | Immobiliare | [Real Estate](/locus-pro/parse/real-estate) | 6 |
| 64 | Quiver Quantitative | [Finance & Markets](/locus-pro/parse/finance) | 3 |
| 65 | Artificial Analysis | [Developer Tools](/locus-pro/parse/developer-tools) | 9 |
| 66 | Mercado Libre Argentina | [Marketplaces](/locus-pro/parse/marketplace) | 6 |
| 67 | UNHCR | [Government & Public Data](/locus-pro/parse/government-public) | 11 |
| 68 | Idealista | [Real Estate](/locus-pro/parse/real-estate) | 4 |
| 69 | ESPN | [Sports](/locus-pro/parse/sports) | 9 |
| 70 | Flashscore | [Sports](/locus-pro/parse/sports) | 17 |
| 71 | PropertyGuru Singapore | [Real Estate](/locus-pro/parse/real-estate) | 6 |
| 72 | National Stock Exchange of India | [Finance & Markets](/locus-pro/parse/finance) | 21 |
| 73 | Mercari Japan | [Marketplaces](/locus-pro/parse/marketplace) | 6 |
| 74 | IAEA PRIS | [Government & Public Data](/locus-pro/parse/government-public) | 6 |
| 75 | AlienVault | [Developer Tools](/locus-pro/parse/developer-tools) | 7 |
| 76 | AutoTrader | [Automotive](/locus-pro/parse/automotive) | 4 |
| 77 | Indonesia Stock Exchange | [Finance & Markets](/locus-pro/parse/finance) | 12 |
| 78 | Target | [E-commerce](/locus-pro/parse/ecommerce) | 6 |
| 79 | Oddschecker | [Sports](/locus-pro/parse/sports) | 9 |
| 80 | SeatGeek | [Entertainment](/locus-pro/parse/entertainment) | 8 |
| 81 | IEEE Xplore | [Education](/locus-pro/parse/education) | 7 |
| 82 | Finviz | [Finance & Markets](/locus-pro/parse/finance) | 6 |
| 83 | arXiv Export | [Education](/locus-pro/parse/education) | 2 |
| 84 | FIDE Ratings | [Sports](/locus-pro/parse/sports) | 4 |
| 85 | Zocdoc | [Healthcare](/locus-pro/parse/healthcare) | 7 |
| 86 | Yad2 | [Real Estate](/locus-pro/parse/real-estate) | 6 |
| 87 | Poe.ninja | [Entertainment](/locus-pro/parse/entertainment) | 5 |
| 88 | StreetEasy | [Real Estate](/locus-pro/parse/real-estate) | 3 |
| 89 | UK Legislation | [Government & Public Data](/locus-pro/parse/government-public) | 3 |
| 90 | Transfermarkt (Germany) | [Sports](/locus-pro/parse/sports) | 8 |
| 91 | Pinnacle | [Sports](/locus-pro/parse/sports) | 8 |
| 92 | Deutsche Bahn | [Travel](/locus-pro/parse/travel) | 2 |
| 93 | Indeed Canada | [Jobs](/locus-pro/parse/jobs) | 6 |
| 94 | Yahoo Finance | [Finance & Markets](/locus-pro/parse/finance) | 3 |
| 95 | Blocket | [Marketplaces](/locus-pro/parse/marketplace) | 9 |
| 96 | Basketball Reference | [Sports](/locus-pro/parse/sports) | 5 |
This directory is part of the [Locus Pro catalog](/locus-pro/catalog-directory), whose September 2026 snapshot contains **3,811 services** and **15,977 callable endpoints**.
# Sandbox keys
Source: https://docs.paywithlocus.com/locus-pro/sandbox
Test your integration's requests and billing handling without spending credits.
A sandbox key lets you build and test direct API integrations before funding live calls. It checks authentication and request validation and returns simulated billing headers. It makes no provider requests, moves no credits, and creates no call history.
Use sandbox for request handling and automated tests. Verify provider-specific
content with a live call before launch.
## Create a key
In your enterprise workspace, open **API Keys → Workspace keys**, select **Create key**, and choose **Sandbox**. Store the returned `lcrsb_…` value; it is shown once.
Sandbox keys support rotation and expiry through the same key-management tools as other workspace keys.
## Make a test call
```bash title="Make a sandbox call" theme={null}
curl --fail-with-body -i \
https://api.paywithlocus.com/api/wrapped/credits/v1/chat/completions \
-H "Authorization: Bearer $LOCUS_SANDBOX_KEY" \
-H "Idempotency-Key: sandbox-chat-1" \
-H "Content-Type: application/json" \
-d '{
"model":"gpt-4o-mini",
"messages":[{"role":"user","content":"Summarize what this integration does."}]
}'
```
Check the response:
| Value | Expected result |
| -------------------------- | -------------------------------------------------------- |
| `X-Locus-Sandbox` | `true` |
| Call ID | Returned for the simulated call |
| Charge and balance headers | Simulated values in your workspace's credit denomination |
The balance never changes.
## What you can test
| Test | Sandbox behavior |
| ---------------------------------------------- | ------------------------------------------------------------------ |
| Direct catalog requests and compatibility chat | Validates the endpoint and request body |
| Allowed-tool restrictions | Rejects endpoints outside the key's allowlist |
| Billing headers and call status | Returns simulated values in the live format |
| Same-request retries | Returns the same call ID and response for the same idempotency key |
Selected providers return approximate fixtures. Other registered providers return a generic sandbox response. These responses are unsuitable for verifying a provider-specific parser.
## What needs a live connection
Use a funded connection for Recipes, live-quoted MPP and x402 services, provider content, and real payment behavior. Sandbox keys cannot access management APIs or MCP.
Sandbox does not detect reusing an idempotency key for a different request.
Live calls do.
Sandbox tests leave no balances or test users to retire. If you create live test identities, follow [Clean up integration tests](/locus-pro/clean-up-integration-tests).
# Node SDK
Source: https://docs.paywithlocus.com/locus-pro/sdk
Add paid tools, track usage, and manage customer balances from your server.
Use `@withlocus/credits` to call tools and build usage billing in Locus Pro Enterprise. The SDK handles idempotency, retries, and cost headers so your application can work with the result.
## Make a call
The current release of `@withlocus/credits` is `0.5.2`.
```bash title="Terminal" theme={null}
npm install @withlocus/credits
```
Enable `tavily/search` in your workspace and fund the balance, then:
```typescript title="Search and read the cost" theme={null}
import { LocusCredits } from "@withlocus/credits";
const locus = new LocusCredits(process.env.LOCUS_SECRET_KEY!);
try {
const result = await locus.callJson("tavily/search", {
query: "latest developments in agent payments",
});
console.log(result.data);
console.log(result.cost.credits);
console.log(result.cost.balance);
} catch (error) {
console.error("Locus call failed", error);
throw error;
}
```
Use a secret key for trusted server operations and a scoped [Agent Connection](#agent-connections) for agent execution. This package runs on your server. For browser UI, use the [widget](/locus-pro/widget).
## `call()`
Pass a `provider/endpoint` slug and the provider's request body.
| Method | Result |
| ---------------------- | ------------------------------------------------------------ |
| `callJson()` | Parsed JSON in `data` |
| `callText()` | Text in `data` |
| `call()` / `callRaw()` | A raw `Response` in `response`, which you can read or stream |
Every method returns `cost.credits` and `cost.balance` as exact decimal strings. Secret-key calls also include `cost.baseUsd`.
To bill an end user and tag the call:
```typescript title="Charge a customer" theme={null}
const result = await locus.callJson(
"tavily/search",
{ query: "agent payments" },
{ user: "user_123", attribution: { project: "prospect-research" } },
);
```
| Call option | Purpose |
| ---------------- | ---------------------------------------------------------------------- |
| `user` | Charge this end-user account at your price; omit for the platform pool |
| `attribution` | Attach searchable metadata to the ledger entry |
| `idempotencyKey` | Reuse a key across process restarts or your own retries |
| `loopId` | Share a run budget across calls; required for per-loop limits |
| `signal` | Cancel the local request with an `AbortSignal` |
The SDK generates one idempotency key per call and reuses it during retries. If your application retries after a restart, supply the original key.
## Agent connections
Create an execution credential on your trusted backend using a secret key with
both `credentials:manage` and `credits:move`:
```typescript title="Create a scoped connection" theme={null}
const connection = await locus.agentConnections.create({
name: "research-agent-prod",
mode: "platform",
tools: { enable: ["tavily/search", "firecrawl/scrape"] },
maxCreditsPerCall: "250",
maxCreditsPerLoop: "1500",
expiresIn: "30d",
});
```
Save `connection.credential` securely. It is revealed only on creation or rotation. Use it in a separate runtime client:
```typescript title="Use the connection in your runtime" theme={null}
const agent = new LocusCredits(process.env.LOCUS_AGENT_CONNECTION!);
const result = await agent.callJson(
"tavily/search",
{ query: "agent payment infrastructure" },
{ loopId: "run_42" },
);
```
Use `mode: "end_user"` with `externalUserId` to bind a connection to one customer. Account and tool scope are fixed at creation. The API and dashboard also support per-connection pricing overrides, which the 0.5.2 typed helper does not expose.
The lifecycle methods are `list()`, `get(id)`, `rotate(id)`, and `revoke(id)`.
Rotation needs both scopes above; listing, reading, and revoking need
`credentials:manage`. See [Connect an agent](/locus-pro/connect-agents) for setup
and budgets.
## Framework MCP presets
Presets turn a connection into the configuration your framework expects:
```typescript title="Framework presets" theme={null}
import {
openAIResponsesMcpTool,
vercelAIMcpTransport,
langChainMcpServer,
} from "@withlocus/credits";
openAIResponsesMcpTool(connection);
vercelAIMcpTransport(connection);
langChainMcpServer(connection);
```
[Framework integrations](/locus-pro/frameworks) covers OpenAI, Anthropic, Google, Vercel, LangChain, LlamaIndex, CrewAI, AutoGen, Mastra, and raw MCP.
## `balance()`
```typescript title="Check pool and customer balances" theme={null}
const pool = await locus.balance();
const customer = await locus.balance("user_123");
console.log(pool.credits);
console.log(customer.credits);
```
## `searchTools()`
Find enabled tools by describing a capability:
```typescript title="Search enabled tools" theme={null}
const tools = await locus.searchTools("current web evidence", {
limit: 5,
user: "user_123",
});
```
Results include the execution slug, input schema, example arguments, and pricing. Passing `user` also applies that customer's tool policy.
## `ledger()`
Read usage with customer and attribution filters:
```typescript title="Read customer usage" theme={null}
const page = await locus.ledger({
user: "user_123",
category: "burn",
attribution: { project: "prospect-research" },
limit: 50,
});
```
Read `page.entries` and pass `page.nextCursor` as `cursor` for the next page.
## `allocate()` / `deallocate()`
Move credits between the platform pool and a customer:
```typescript title="Move credits" theme={null}
await locus.allocate("user_123", { credits: "5000" });
await locus.deallocate("user_123", { credits: "1000" });
```
Transfers cannot overdraw the source account. Supply an `idempotencyKey` when retrying the same transfer.
## `topup()`
Create a hosted Stripe Checkout session:
```typescript title="Create a top-up session" theme={null}
const session = await locus.topup({
usd: "100.00",
successUrl: "https://yourapp.com/billing?ok=1",
cancelUrl: "https://yourapp.com/billing",
});
// Redirect the buyer to session.url.
```
Omit `externalUserId` to fund the platform pool; include it to fund a customer. Send either `usd` or `credits` as an exact decimal string.
Use `topupConstraints()` for current limits and `topupStatus(session.sessionId)` to confirm that payment has completed. See [Funding & billing](/locus-pro/funding-and-billing) for funding options.
## `endUserToken()`
Mint a short-lived token for the [widget](/locus-pro/widget) from an authenticated server route:
```typescript title="Mint a browser token" theme={null}
const { token, expiresAt } = await locus.endUserToken(currentUser.id);
```
Derive the user ID from your server session. Send the token to that user's browser and keep the secret key on the server.
## End-user catalog
The browser packages `@withlocus/credits-js` and `@withlocus/credits-react` export `fetchCatalog` for customer-facing tool lists. It returns allowed tools and final prices without exposing your costs or margins. See [Render the provider catalog](/locus-pro/widget#render-the-provider-catalog).
## Errors
```typescript title="Handle insufficient credits" theme={null}
import { LocusInsufficientCreditsError } from "@withlocus/credits";
try {
await locus.callJson(
"tavily/search",
{ query: "company funding news" },
{ user: "user_123" },
);
} catch (error) {
if (error instanceof LocusInsufficientCreditsError) {
// Show your top-up flow; error.topupUrl may provide a hosted link.
console.error("More credits needed", error.requiredCredits);
} else {
throw error;
}
}
```
| Error | Meaning |
| ------------------------------- | --------------------------------------------------- |
| `LocusApiError` | A non-success response; inspect `status` and `body` |
| `LocusInsufficientCreditsError` | Insufficient balance (`402`) |
| `LocusRateLimitError` | Rate limit reached after retries (`429`) |
## Constructor
```typescript title="Configure the client" theme={null}
new LocusCredits(credential, options);
```
| Option | Default | Purpose |
| ---------------------------- | ------------------------------ | ------------------------------------------------------------ |
| `baseUrl` | `https://api.paywithlocus.com` | API origin |
| `maxRetries` | `2` | Retries for rate limits, server errors, and network failures |
| `timeoutMs` | `120000` | Timeout per attempt |
| `retryBaseMs` / `retryMaxMs` | `250` / `4000` | Backoff timing |
| `fetch` | Global `fetch` | Custom transport |
See the [API reference](/api-reference/introduction) for complete request and response contracts.
# Widget
Source: https://docs.paywithlocus.com/locus-pro/widget
Add customer balances, usage history, and credit top-ups to your product.
Give customers a live balance and an **Add credits** button without building a billing screen. The Locus Pro Enterprise widget opens hosted Stripe Checkout, then refreshes the balance when payment completes.
Use `@withlocus/credits-react` in React or `@withlocus/credits-js` in any web app. Customers see their balance and your prices; your costs and margins stay private.
## Mint a token on your server
The widget needs your publishable key and a short-lived token for the signed-in user:
```typescript title="Authenticated server route" theme={null}
import { LocusCredits } from "@withlocus/credits";
const locus = new LocusCredits(process.env.LOCUS_SECRET_KEY!);
// Inside an authenticated route handler:
const { token } = await locus.endUserToken(currentUser.id);
return { userToken: token };
```
Derive `currentUser.id` from your server session. Never send the secret key
to the browser.
Tokens last at most one hour; use `renewUserToken` to refresh them.
## Add the widget
```bash title="Install the React package" theme={null}
npm install @withlocus/credits-react
```
```tsx title="Billing.tsx" theme={null}
import { CreditsBalance } from "@withlocus/credits-react";
function Billing({ userToken }: { userToken: string }) {
return (
console.log("Balance updated")}
/>
);
}
```
```html title="Mount the widget" theme={null}
```
Pass the token returned by your authenticated server route. The returned handle provides `refresh()` and `destroy()`.
The default top-up is **\$5**. Set `topupUsd` or `topupCredits` to change the amount.
## Show transaction history
Set `showPerCallPricing` to display the five most recent charges, top-ups, allocations, and refunds. The history refreshes with the balance and shows only the signed-in user's activity.
For custom React UI, use `fetchLedger`:
```typescript title="Load transaction history" theme={null}
import { fetchLedger } from "@withlocus/credits-react";
const entries = await fetchLedger(
{
baseUrl: "https://api.paywithlocus.com",
publishableKey: "lcrpk_...",
userToken,
},
20,
);
```
See [Own transaction history](/api-reference/widget/own-ledger-end-user) for pagination and response fields.
## Render the provider catalog
Show customers which tools they can use and what they cost:
```typescript title="Load the customer catalog" theme={null}
import { fetchCatalog } from "@withlocus/credits-react";
const catalog = await fetchCatalog(
{
baseUrl: "https://api.paywithlocus.com",
publishableKey: "lcrpk_...",
userToken,
},
{ category: "AI / LLM", pageSize: 25 },
);
```
The helper loads the pages for you. Results include provider names, logos, allowed endpoints, and final credit prices. Variable-price tools are marked as dynamic.
## Build your own balance UI
```tsx title="Custom balance hook" theme={null}
import { useCreditsBalance } from "@withlocus/credits-react";
const { credits, loading, error, refresh } = useCreditsBalance({
publishableKey: "lcrpk_...",
userToken,
});
```
Render the loading and error states alongside the balance.
## Customization
| Option | Default | Purpose |
| ------------------------------------ | ------------------------------ | ---------------------------------------------------- |
| `publishableKey` / `userToken` | Required | Browser authentication |
| `baseUrl` | `https://api.paywithlocus.com` | API origin |
| `showTopup` | `true` | Show the purchase button |
| `topupUsd` | `"5.00"` | Purchase amount in USD |
| `topupCredits` | None | Purchase amount in credits; overrides `topupUsd` |
| `topupLabel` | `"Add credits"` | Button text |
| `showPerCallPricing` | `false` | Show recent transactions |
| `pollIntervalMs` | `15000` | Refresh interval; `0` disables polling |
| `renewUserToken` | None | Async callback for a fresh token after a `401` |
| `onTopup` | None | Callback after completed payment and balance refresh |
| `topupSuccessUrl` / `topupCancelUrl` | Current page | Checkout return destinations |
| `style` / `className` | None | React container styling |
The widget also supports checkout lifecycle callbacks, top-up metadata, and session binding.
## Next steps
* [Funding & billing](/locus-pro/funding-and-billing): choose how customer balances are funded.
* [SDK reference](/locus-pro/sdk): mint tokens and charge usage from your server.
# Platform walkthrough
Source: https://docs.paywithlocus.com/platform-walkthrough
Manage your agent's balance, spending limits, tools, and payments.
The [Locus dashboard](https://app.paywithlocus.com) shows what your agent can spend, what it has spent, and which actions need your approval.
## Wallet
The **Overview** page shows your wallet address and USDC balance on Base.
* **Fund** adds money through Coinbase Pay.
* **Send** transfers USDC to a Base wallet address or an email recipient.
See [wallets](/features/wallets) for recovery keys and [email sends](/features/wallets#subwallets).
## Agent settings
### API key
Use this key to connect your agent. Regenerate it if you need to replace its credentials.
### Agent spend limits
| Setting | What it controls |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Allowance** | Total authorized spending. The remaining allowance decreases as your agent spends. Leave blank to allow access to the full wallet balance. |
| **Max transaction size** | The most your agent can spend in one transaction. |
| **Approval threshold** | Payments above this amount need your approval. Set to **\$0** to review every payment, or leave blank to require no approvals. |
You can adjust these limits at any time.
## Agent tools
Open **Services → Agent tools** to search by provider, capability, source, or category.
* Review a provider's tools, request fields, and estimated prices.
* Use provider and tool toggles to restrict your agent. Locus-managed tools start enabled.
* Select **Add custom tool** to register another paid endpoint.
* Browse external listings from Parse, Merit Systems, MPP, and Orthogonal.
Changes to tool access take effect immediately. See [agent tools](/wrapped-apis/index).
## Build with Locus
Use the **Build** tab to view projects, track deployments, inspect logs, manage Postgres or Redis addons, and connect domains. Your agent can deploy through the API while you follow progress in the dashboard.
See [Build with Locus](/build/index) to deploy your first service.
## Checkout
The **Checkout** tab contains your products, checkout transactions, merchant API key, and integration details.
See [Checkout with Locus](/checkout/index) to accept USDC payments.
## Transactions
Review transfers, tool charges, and checkout payments in **Transactions**. Each entry includes its amount, recipient, timestamp, and the agent's reasoning when available.
## Approvals
Payments above your approval threshold appear in **Approvals**. Approve or deny each request; your agent receives the outcome.
# Request and claim credits
Source: https://docs.paywithlocus.com/promo-credits
Request promotional USDC to try the Agent Platform.
Request **5–50 USDC** in promotional credits to try Agent Platform tools, payments, and deployments. If approved, you'll receive a gift code by email to redeem into your wallet.
## Request credits
Ask your agent to submit your email, GitHub repository, requested amount, and a short description of what you're building. You can request credits before creating an account.
```bash title="Request promotional credits" theme={null}
curl --fail-with-body -X POST https://api.paywithlocus.com/api/gift-code-requests \
-H "Content-Type: application/json" \
-d '{
"email": "you@example.com",
"reason": "Testing paid web research for my open-source agent",
"githubUrl": "https://github.com/your-username/your-project",
"requestedAmountUsdc": 10
}'
```
All four fields are required. The reason must be at least 10 characters. You can submit one request per email address every 24 hours.
## What happens after you request
Requests are reviewed before credits are issued. If approved, you'll receive a code in the format `XXX-XXX-XXX-XXX`.
## Claim credits
1. Sign in to the [Locus dashboard](https://app.paywithlocus.com).
2. Open the redemption section and enter your code.
3. Check your wallet for the added USDC.
Create your wallet first if you haven't already. The [quickstart](/quickstart) walks through setup.
Signed-in users can request credits through `POST /api/users/gift-code-request`. Send `reason`, `githubUrl`, and `requestedAmountUsdc`; your email comes from your account.
To redeem a code:
```bash title="Redeem a gift code" theme={null}
curl --fail-with-body -X POST https://api.paywithlocus.com/api/users/redeem-code \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"code": "XXX-XXX-XXX-XXX", "walletId": "your-wallet-id"}'
```
Both endpoints require a signed-in user's JWT. A `claw_` agent key cannot redeem a code.
## Other ways to fund your wallet
Send **USDC on Base** to the address in your dashboard, or use the dashboard's on-ramp where available. Direct funding lets you start without waiting for a credit request.
# Quickstart
Source: https://docs.paywithlocus.com/quickstart
Connect your agent to a USDC wallet with spending controls.
Send this to your agent:
```text title="Send to your agent" wrap theme={null}
Read https://paywithlocus.com/skill.md and help me set up an Agent Platform wallet.
```
Your agent loads the instructions for payments, tools, and deployments. You'll create a wallet, give it an API key, and choose its spending limits.
## Set up your wallet
Sign up at [app.paywithlocus.com](https://app.paywithlocus.com) and verify your email.
Click **Create Wallet** in the dashboard. Save the private key securely; it is your recovery key. Deployment on Base takes about 30 seconds.
Under **API Key**, click **Generate API Key**. Copy the `claw_dev_` key when it appears and give it to your agent through your agent client's credential setup. The key is shown only once.
To test first, use the **sandbox key** (`claw_sandbox_`). It returns simulated responses without moving money or spending credits.
Send **USDC on Base** to the address in your dashboard, or [request promotional credits](/promo-credits).
Set an **allowance** for total spending, a **maximum transaction size**, and an **approval threshold** for payments you want to review.
## Try it
Ask your agent to check its balance and available tools:
> Check my Locus wallet balance, then find the tools available for web research. Don't make any paid calls yet.
You can also check the connection directly:
```bash title="Check your wallet balance" theme={null}
curl --fail-with-body https://api.paywithlocus.com/api/pay/balance \
-H "Authorization: Bearer YOUR_LOCUS_API_KEY"
```
A successful response includes your USDC balance and wallet address. If you receive `401`, check that you copied the current key from the dashboard.
## Test without spending
The sandbox key works on agent endpoints before you fund the wallet, including while the wallet is deploying. It simulates spending controls against a fixed 25 USDC balance, so you can test approvals and limit handling. Responses include `X-Locus-Sandbox: true`.
Agents that register through `POST /api/register` receive both production and sandbox keys. See the [onboarding reference](https://paywithlocus.com/onboarding.md) for agent-led setup.
## Production endpoints
| Resource | URL |
| ----------- | ------------------------------------------------------- |
| API | `https://api.paywithlocus.com/api` |
| Dashboard | [app.paywithlocus.com](https://app.paywithlocus.com) |
| Agent skill | [skill.md](https://paywithlocus.com/skill.md) |
| Onboarding | [onboarding.md](https://paywithlocus.com/onboarding.md) |
## Next steps
Give your agent paid search, data, and model access.
Review spending and manage your agent from the dashboard.
# Use agent tools
Source: https://docs.paywithlocus.com/wrapped-apis/for-agents
Connect your agent, check a price, and call a tool from your USDC wallet.
Send your agent [skill.md](https://paywithlocus.com/skill.md) to use Agent Platform tools from its USDC wallet. For a direct integration, the core flow is discover, quote, and call.
The routes below use an Agent Platform API key. For Locus Pro with prepaid credits and MCP, see its [quickstart](/locus-pro/individual/quickstart).
## Authentication
Create an agent API key in the [Locus dashboard](https://app.paywithlocus.com). Use it as a Bearer token when quoting, calling a tool, or retrieving a result. Catalog discovery is public.
## Discover registered tools
Fetch the catalog for one provider:
```bash title="Discover Firecrawl tools" theme={null}
curl --fail-with-body -sS \
"https://api.paywithlocus.com/api/wrapped?provider=firecrawl"
```
Omit `provider` to list all tools. The response includes exact `provider/endpoint` slugs in `data.endpoints` and display metadata in `data.catalog`.
The [provider reference](https://paywithlocus.com/wapi/firecrawl.md) supplies request fields, examples, and estimated pricing. See the [catalog](/wrapped-apis/providers) for every provider's reference.
## Quote a call
Send your intended request to its `/quote` route. This checks the inputs and price without calling the provider:
```bash title="Quote a scrape request" theme={null}
curl --fail-with-body -X POST https://api.paywithlocus.com/api/wrapped/firecrawl/scrape/quote \
-H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","formats":["markdown"]}'
```
Read the total from `data.price_usdc` or `X-Locus-Cost-Usd`. Calls have a **\$0.001 minimum**. A provider's free endpoint can still carry a Locus fee.
## Make a call
Send the same body to the tool route. Use a unique `Idempotency-Key` for each logical call and reuse it for retries. To lock the quoted price, set `X-Locus-Expected-Cost-Usd` to the value you just received.
```bash title="Run the quoted request" theme={null}
curl --fail-with-body -X POST https://api.paywithlocus.com/api/wrapped/firecrawl/scrape \
-H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
-H "Idempotency-Key: 2e0c4b53-47de-4b80-8749-63ec9945e6b3" \
-H "X-Locus-Expected-Cost-Usd: 0.003830" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","formats":["markdown"]}'
```
Replace the example price with your quote. A successful response contains the provider result in `data`. A changed price returns `409 PRICE_CHANGED` before the provider is called.
## Approval flow
Calls above your approval threshold return `202` with an `approval_url` and `result_path`.
1. Open or share the approval URL.
2. After approval, Locus executes the stored request.
3. Fetch `result_path` with the same Bearer key, or retry the identical request with its original `Idempotency-Key`.
Keep the original key throughout the flow to avoid creating a second call.
## Enable and disable tools
Open **Services → Agent tools** in the dashboard. Locus-managed tools start enabled; provider and tool toggles restrict access immediately.
## Error handling
| Response | What to do |
| ---------------- | ------------------------------------------------------------ |
| `401` | Check your API key. |
| `402` | Fund the wallet. |
| `403` | Check tool access, spending limits, or approval status. |
| `409` | Read the response for a price change or an in-progress call. |
| Provider failure | Check whether the request was dispatched before retrying. |
`X-Locus-Retry-Safe: true` confirms that no provider request was dispatched. Without that confirmation, a failed response can still represent work the provider accepted. Preserve the original idempotency key for any same-route retry.
For full request contracts and provider-specific errors, use the generated references in the [tool catalog](/wrapped-apis/providers).
# Agent tools
Source: https://docs.paywithlocus.com/wrapped-apis/index
Give your agent search, data, AI models, and other paid tools from one USDC balance.
Your agent can search the web, read company data, generate media, or call an AI model without separate provider accounts. Locus manages provider credentials and charges each call to your USDC balance.
Use the [tool catalog](/wrapped-apis/providers) to find a provider. Your agent's allowance, transaction limit, and approval threshold apply to every paid call.
## What you can build
| Task | Example tools |
| -------------------------------------- | -------------------------------------------- |
| Research with current sources | Exa, Brave Search, Firecrawl, and Perplexity |
| Enrich a prospect or company | Apollo, Hunter, BuiltWith, and Clado |
| Add models, images, or voice to an app | OpenAI, Anthropic, fal.ai, and ElevenLabs |
| Work with specialized data | Alpha Vantage, EDGAR, Mapbox, and RentCast |
## How it works
Search the dashboard or let your agent discover tools from the public catalog.
Your agent can quote the exact request before spending. Prices depend on the tool and inputs.
Locus authenticates with the provider, enforces your spending controls, and returns the response.
## Pricing
Pay per call from your wallet or available promotional credits. The quote includes provider usage and Locus fees, with a **\$0.001 minimum charge**. Generated catalog prices are estimates; quote the exact request for its total.
The API supports a price lock and idempotency keys to prevent duplicate execution on retries. See [quoting and calls](/wrapped-apis/for-agents#quote-a-call).
## Human approval
If a call exceeds your approval threshold, your agent gives you an approval link. Approval starts the stored request automatically, and your agent collects the result.
Set your limits in [agent settings](/platform-walkthrough#agent-settings).
## Manage tools in the dashboard
Open **Services → Agent tools** in the [dashboard](https://app.paywithlocus.com). Review a tool's inputs and estimated price, then use provider and tool toggles to control access. Locus-managed tools start enabled.
The directory also lists tools from Parse, Merit Systems, MPP, and Orthogonal. External listings use their own discovery and execution paths. Choose **Add custom tool** to register another paid endpoint.
## Next steps
Connect, quote a request, and make a call.
Browse providers and request references.
Pay from a Tempo wallet through HTTP 402.
# MPP tool payments
Source: https://docs.paywithlocus.com/wrapped-apis/mpp
Pay for supported agent tools inline through HTTP 402 on Tempo.
Call supported Locus tools and pay from a Tempo wallet funded with **USDC.e**. MPP uses an HTTP 402 payment challenge, so your agent can buy a result without first opening or funding a Locus account.
## How it works
Send the provider request to its MPP endpoint without a payment credential.
The response identifies the price, USDC.e token, Tempo recipient, and payment requirements.
Inspect the challenge, sign the payment with the Tempo wallet, and resend the same request with the resulting payment credential.
Locus verifies payment and dispatches the validated request to the provider.
## Pricing
The payment challenge shows the actual price and asset. Check both before signing; catalog prices are estimates.
Most tools charge once per request. Origami Research charges for usage within a budget you set.
## Refunds for one-time calls
If a provider fails after a one-time payment settles, Locus attempts to refund USDC.e to the same Tempo wallet. A completed refund includes both `refunded: true` and `refundTxHash` in the error response.
Refunds can fail. Check for both confirmation fields before treating the payment as returned.
## Origami usage sessions
Origami Research uses an MPP usage session over server-sent events instead of a one-time payment. It bills **\$0.018 per settled `origami_credit`**.
Set `maxCredits` to cap the run's budget, from **5 to 10,000** credits. The suggested deposit funds the channel; the final charge follows billable usage during the stream.
Already metered credits are not automatically refunded if the stream later disconnects or fails. Use the [Origami reference](https://paywithlocus.com/mpp/origami.md) for request fields and session handling.
## Supported providers
MPP supports **37 provider namespaces**, shown as **35 dashboard provider groups** because the Diffbot namespaces share one group.
Send your agent the provider reference for request fields, examples, prices, and the correct MPP host:
### A–D
| Provider | Reference | Namespace |
| ------------- | -------------------------------------------------------------- | -------------- |
| Alpha Vantage | [Endpoint guide](https://paywithlocus.com/mpp/alphavantage.md) | `alphavantage` |
| Apollo | [Endpoint guide](https://paywithlocus.com/mpp/apollo.md) | `apollo` |
| Billboard | [Endpoint guide](https://paywithlocus.com/mpp/billboard.md) | `billboard` |
| Brave Search | [Endpoint guide](https://paywithlocus.com/mpp/brave.md) | `brave` |
| BuiltWith | [Endpoint guide](https://paywithlocus.com/mpp/builtwith.md) | `builtwith` |
| Clado | [Endpoint guide](https://paywithlocus.com/mpp/clado.md) | `clado` |
| CoinGecko | [Endpoint guide](https://paywithlocus.com/mpp/coingecko.md) | `coingecko` |
| Deepgram | [Endpoint guide](https://paywithlocus.com/mpp/deepgram.md) | `deepgram` |
| DeepL | [Endpoint guide](https://paywithlocus.com/mpp/deepl.md) | `deepl` |
| DeepSeek | [Endpoint guide](https://paywithlocus.com/mpp/deepseek.md) | `deepseek` |
| Diffbot | [Endpoint guide](https://paywithlocus.com/mpp/diffbot.md) | `diffbot` |
| Diffbot KG | [Endpoint guide](https://paywithlocus.com/mpp/diffbot-kg.md) | `diffbot-kg` |
| Diffbot NL | [Endpoint guide](https://paywithlocus.com/mpp/diffbot-nl.md) | `diffbot-nl` |
### E–M
| Provider | Reference | Namespace |
| ---------------------- | -------------------------------------------------------------- | -------------- |
| EDGAR (SEC) | [Endpoint guide](https://paywithlocus.com/mpp/edgar.md) | `edgar` |
| EDGAR Full-Text Search | [Endpoint guide](https://paywithlocus.com/mpp/edgar-search.md) | `edgar-search` |
| Grok | [Endpoint guide](https://paywithlocus.com/mpp/grok.md) | `grok` |
| Groq | [Endpoint guide](https://paywithlocus.com/mpp/groq.md) | `groq` |
| Hunter | [Endpoint guide](https://paywithlocus.com/mpp/hunter.md) | `hunter` |
| IPinfo | [Endpoint guide](https://paywithlocus.com/mpp/ipinfo.md) | `ipinfo` |
| Judge0 | [Endpoint guide](https://paywithlocus.com/mpp/judge0.md) | `judge0` |
| Mapbox | [Endpoint guide](https://paywithlocus.com/mpp/mapbox.md) | `mapbox` |
| Mathpix | [Endpoint guide](https://paywithlocus.com/mpp/mathpix.md) | `mathpix` |
| Mistral AI | [Endpoint guide](https://paywithlocus.com/mpp/mistral.md) | `mistral` |
### O–Z
| Provider | Reference | Namespace |
| ------------------ | --------------------------------------------------------------- | --------------- |
| OFAC Sanctions API | [Endpoint guide](https://paywithlocus.com/mpp/ofac.md) | `ofac` |
| OpenWeather | [Endpoint guide](https://paywithlocus.com/mpp/openweather.md) | `openweather` |
| Origami | [Endpoint guide](https://paywithlocus.com/mpp/origami.md) | `origami` |
| Parallel | [Endpoint guide](https://paywithlocus.com/mpp/parallel.md) | `parallel` |
| Perplexity | [Endpoint guide](https://paywithlocus.com/mpp/perplexity.md) | `perplexity` |
| RentCast | [Endpoint guide](https://paywithlocus.com/mpp/rentcast.md) | `rentcast` |
| Replicate | [Endpoint guide](https://paywithlocus.com/mpp/replicate.md) | `replicate` |
| ScreenshotOne | [Endpoint guide](https://paywithlocus.com/mpp/screenshotone.md) | `screenshotone` |
| Stability AI | [Endpoint guide](https://paywithlocus.com/mpp/stability-ai.md) | `stability-ai` |
| Suno | [Endpoint guide](https://paywithlocus.com/mpp/suno.md) | `suno` |
| Tavily | [Endpoint guide](https://paywithlocus.com/mpp/tavily.md) | `tavily` |
| VirusTotal | [Endpoint guide](https://paywithlocus.com/mpp/virustotal.md) | `virustotal` |
| Wolfram\|Alpha | [Endpoint guide](https://paywithlocus.com/mpp/wolframalpha.md) | `wolframalpha` |
| ZeroBounce | [Endpoint guide](https://paywithlocus.com/mpp/zerobounce.md) | `zerobounce` |
Fetch only the provider needed for the current task. For example: `curl -s https://paywithlocus.com/mpp/parallel.md`.
Each provider host also exposes an OpenAPI 3.1 discovery document at `https://.mpp.paywithlocus.com/openapi.json`.
# Agent tool catalog
Source: https://docs.paywithlocus.com/wrapped-apis/providers
Find a provider for search, data, models, media, and other agent tasks.
Browse **295 tools** across **50 provider namespaces**. Each WAPI link gives your agent the request fields, examples, and estimated prices for that provider. MPP links cover direct payment from a Tempo wallet.
For research, start with Exa, Firecrawl, or Perplexity. For company data, try Apollo, BuiltWith, or Clado. Use the dashboard to search by category and control tool access.
Catalog prices are estimates. Quote your request or check its payment challenge for the actual total.
## Providers
### A–D
| Provider | Request references | Tools | Namespace |
| ------------- | ----------------------------------------------------------------------------------------------------------- | ----: | -------------- |
| Alpha Vantage | [WAPI](https://paywithlocus.com/wapi/alphavantage.md) · [MPP](https://paywithlocus.com/mpp/alphavantage.md) | 26 | `alphavantage` |
| Anthropic | [WAPI](https://paywithlocus.com/wapi/anthropic.md) | 3 | `anthropic` |
| Apollo | [WAPI](https://paywithlocus.com/wapi/apollo.md) · [MPP](https://paywithlocus.com/mpp/apollo.md) | 8 | `apollo` |
| Billboard | [WAPI](https://paywithlocus.com/wapi/billboard.md) · [MPP](https://paywithlocus.com/mpp/billboard.md) | 2 | `billboard` |
| Brave Search | [WAPI](https://paywithlocus.com/wapi/brave.md) · [MPP](https://paywithlocus.com/mpp/brave.md) | 6 | `brave` |
| Browser Use | [WAPI](https://paywithlocus.com/wapi/browser-use.md) | 4 | `browser-use` |
| BuiltWith | [WAPI](https://paywithlocus.com/wapi/builtwith.md) · [MPP](https://paywithlocus.com/mpp/builtwith.md) | 12 | `builtwith` |
| Clado | [WAPI](https://paywithlocus.com/wapi/clado.md) · [MPP](https://paywithlocus.com/mpp/clado.md) | 10 | `clado` |
| CoinGecko | [WAPI](https://paywithlocus.com/wapi/coingecko.md) · [MPP](https://paywithlocus.com/mpp/coingecko.md) | 15 | `coingecko` |
| DataForSEO | [WAPI](https://paywithlocus.com/wapi/dataforseo.md) | 2 | `dataforseo` |
| Deepgram | [WAPI](https://paywithlocus.com/wapi/deepgram.md) · [MPP](https://paywithlocus.com/mpp/deepgram.md) | 5 | `deepgram` |
| DeepL | [WAPI](https://paywithlocus.com/wapi/deepl.md) · [MPP](https://paywithlocus.com/mpp/deepl.md) | 3 | `deepl` |
| DeepSeek | [WAPI](https://paywithlocus.com/wapi/deepseek.md) · [MPP](https://paywithlocus.com/mpp/deepseek.md) | 3 | `deepseek` |
| Diffbot | [WAPI](https://paywithlocus.com/wapi/diffbot.md) · [MPP](https://paywithlocus.com/mpp/diffbot.md) | 9 | `diffbot` |
| Diffbot KG | [WAPI](https://paywithlocus.com/wapi/diffbot-kg.md) · [MPP](https://paywithlocus.com/mpp/diffbot-kg.md) | 2 | `diffbot-kg` |
| Diffbot NL | [WAPI](https://paywithlocus.com/wapi/diffbot-nl.md) · [MPP](https://paywithlocus.com/mpp/diffbot-nl.md) | 1 | `diffbot-nl` |
### E–M
| Provider | Request references | Tools | Namespace |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- | ----: | -------------- |
| EDGAR (SEC) | [WAPI](https://paywithlocus.com/wapi/edgar.md) · [MPP](https://paywithlocus.com/mpp/edgar.md) | 3 | `edgar` |
| EDGAR Full-Text Search | [WAPI](https://paywithlocus.com/wapi/edgar-search.md) · [MPP](https://paywithlocus.com/mpp/edgar-search.md) | 1 | `edgar-search` |
| ElevenLabs | [WAPI](https://paywithlocus.com/wapi/elevenlabs.md) | 1 | `elevenlabs` |
| Exa | [WAPI](https://paywithlocus.com/wapi/exa.md) | 4 | `exa` |
| fal.ai | [WAPI](https://paywithlocus.com/wapi/fal.md) | 3 | `fal` |
| Firecrawl | [WAPI](https://paywithlocus.com/wapi/firecrawl.md) | 9 | `firecrawl` |
| Google Gemini | [WAPI](https://paywithlocus.com/wapi/gemini.md) | 5 | `gemini` |
| Grok | [WAPI](https://paywithlocus.com/wapi/grok.md) · [MPP](https://paywithlocus.com/mpp/grok.md) | 8 | `grok` |
| Groq | [WAPI](https://paywithlocus.com/wapi/groq.md) · [MPP](https://paywithlocus.com/mpp/groq.md) | 2 | `groq` |
| Hunter | [WAPI](https://paywithlocus.com/wapi/hunter.md) · [MPP](https://paywithlocus.com/mpp/hunter.md) | 8 | `hunter` |
| IPinfo | [WAPI](https://paywithlocus.com/wapi/ipinfo.md) · [MPP](https://paywithlocus.com/mpp/ipinfo.md) | 1 | `ipinfo` |
| Judge0 | [WAPI](https://paywithlocus.com/wapi/judge0.md) · [MPP](https://paywithlocus.com/mpp/judge0.md) | 5 | `judge0` |
| Mapbox | [WAPI](https://paywithlocus.com/wapi/mapbox.md) · [MPP](https://paywithlocus.com/mpp/mapbox.md) | 8 | `mapbox` |
| Mathpix | [WAPI](https://paywithlocus.com/wapi/mathpix.md) · [MPP](https://paywithlocus.com/mpp/mathpix.md) | 2 | `mathpix` |
| Mistral AI | [WAPI](https://paywithlocus.com/wapi/mistral.md) · [MPP](https://paywithlocus.com/mpp/mistral.md) | 4 | `mistral` |
### O–Z
| Provider | Request references | Tools | Namespace |
| ------------------ | ------------------------------------------------------------------------------------------------------------- | ----: | --------------- |
| OFAC Sanctions API | [WAPI](https://paywithlocus.com/wapi/ofac.md) · [MPP](https://paywithlocus.com/mpp/ofac.md) | 2 | `ofac` |
| OpenAI | [WAPI](https://paywithlocus.com/wapi/openai.md) | 6 | `openai` |
| OpenRouter | [WAPI](https://paywithlocus.com/wapi/openrouter.md) | 1 | `openrouter` |
| OpenWeather | [WAPI](https://paywithlocus.com/wapi/openweather.md) · [MPP](https://paywithlocus.com/mpp/openweather.md) | 7 | `openweather` |
| Origami | [WAPI](https://paywithlocus.com/wapi/origami.md) · [MPP](https://paywithlocus.com/mpp/origami.md) | 1 | `origami` |
| Parallel | [WAPI](https://paywithlocus.com/wapi/parallel.md) · [MPP](https://paywithlocus.com/mpp/parallel.md) | 3 | `parallel` |
| Perplexity | [WAPI](https://paywithlocus.com/wapi/perplexity.md) · [MPP](https://paywithlocus.com/mpp/perplexity.md) | 4 | `perplexity` |
| Ramp Router | [WAPI](https://paywithlocus.com/wapi/ramp-router.md) | 3 | `ramp-router` |
| RentCast | [WAPI](https://paywithlocus.com/wapi/rentcast.md) · [MPP](https://paywithlocus.com/mpp/rentcast.md) | 10 | `rentcast` |
| Replicate | [WAPI](https://paywithlocus.com/wapi/replicate.md) · [MPP](https://paywithlocus.com/mpp/replicate.md) | 4 | `replicate` |
| ScreenshotOne | [WAPI](https://paywithlocus.com/wapi/screenshotone.md) · [MPP](https://paywithlocus.com/mpp/screenshotone.md) | 1 | `screenshotone` |
| Stability AI | [WAPI](https://paywithlocus.com/wapi/stability-ai.md) · [MPP](https://paywithlocus.com/mpp/stability-ai.md) | 26 | `stability-ai` |
| Suno | [WAPI](https://paywithlocus.com/wapi/suno.md) · [MPP](https://paywithlocus.com/mpp/suno.md) | 4 | `suno` |
| Tavily | [WAPI](https://paywithlocus.com/wapi/tavily.md) · [MPP](https://paywithlocus.com/mpp/tavily.md) | 4 | `tavily` |
| VirusTotal | [WAPI](https://paywithlocus.com/wapi/virustotal.md) · [MPP](https://paywithlocus.com/mpp/virustotal.md) | 21 | `virustotal` |
| Whitepages Pro | [WAPI](https://paywithlocus.com/wapi/whitepages.md) | 2 | `whitepages` |
| Wolfram\|Alpha | [WAPI](https://paywithlocus.com/wapi/wolframalpha.md) · [MPP](https://paywithlocus.com/mpp/wolframalpha.md) | 4 | `wolframalpha` |
| X (Twitter) | [WAPI](https://paywithlocus.com/wapi/x.md) | 15 | `x` |
| ZeroBounce | [WAPI](https://paywithlocus.com/wapi/zerobounce.md) · [MPP](https://paywithlocus.com/mpp/zerobounce.md) | 2 | `zerobounce` |
## Discover programmatically
`GET https://api.paywithlocus.com/api/wrapped` returns the current JSON index. Add `?provider=` to return one namespace only. These discovery requests are public; authentication is required when calling a tool.
```bash title="Discover a provider's tools" theme={null}
curl -s "https://api.paywithlocus.com/api/wrapped?provider=firecrawl"
```
The dashboard groups the three Diffbot namespaces into one card, for **48 provider cards** in total. See [using tools](/wrapped-apis/for-agents) for quoting, calling, and approvals.