Quickstart

Start with the path that matches your account. Personal accounts are self-serve and connect MCP clients through browser OAuth. Enterprise workspaces add tenant API keys, server SDKs, end-user balances, markup, the widget, and team controls.

Path	Dashboard navigation	Authentication
Personal	Tools, Credits, Connections	MCP OAuth; no tenant API keys
Enterprise	Agent tools, Funding & billing, API Keys	Tenant keys for trusted servers; OAuth or scoped service credentials for agents

Personal: connect an agent

Create a personal account

Open Locus Pro signup. Use email, Google, GitHub, GitLab, or Ethereum when the method appears. Email signup verifies a six-digit code; Ethereum signup also verifies a recovery email. The account starts at exactly $0 with no free credits.

Choose tools

Open Tools and enable only the ordinary provider endpoints the agent needs. Those entries start disabled, so an unenabled tool cannot spend credits. Where capability routing is available, its system-managed router is already enabled and cannot be toggled like an ordinary provider.

Add credits

Open Credits, choose an amount, and complete Locus-hosted Stripe Checkout. Personal top-ups do not receive enterprise volume bonuses.

Connect the client

Open Connections, copy the hosted MCP URL into a supported client, and complete the browser approval. The client stores and refreshes OAuth tokens; you do not copy a tenant key into it. Included supports one active OAuth-connected client, Plus supports three, and Unlimited removes the active-client cap.

Your client can now discover and call the enabled tools. Every successful call reports its charge and remaining balance. Non-streaming provider failures release their credit reservation; an accepted stream can remain charged after a later disconnect or stream failure. See Connect an agent for client-specific OAuth instructions.

An agent can create its own restricted account through AgentID without a Locus dashboard identity. Use agent-native onboarding.

Enterprise: make an API call

The remaining steps are for an evaluation or enterprise workspace. Personal accounts do not expose API Keys and cannot run this server-key flow.

1. Open or join a workspace

Use your evaluation or team invitation, or complete the enterprise intake arranged with Locus. Sign in and select the enterprise workspace. See Account setup and sign-in for invitation and identity details.

2. Get your keys

Sign in to the Locus Pro dashboard. Add a passkey when prompted if you will create or rotate sensitive credentials. Issue credentials from API Keys in the dashboard:

Key	Prefix	Where it lives	What it does
Secret key	`lcr_…`	Your server, never the browser	Calls APIs, reads balances, mints end-user tokens, manages the catalog
Publishable key	`lcrpk_…`	Safe in the browser	Powers the balance + top-up widget, paired with a per-user token

Your keys are control-plane credentials. Before giving an agent access, create a scoped lcac_… connection with its own tool allowlist, account binding, expiry, and spend limits.

export LOCUS_SECRET_KEY="lcr_...your key..."
export LOCUS_API="https://api.paywithlocus.com"

Treat the secret key like a password. Workspaces can hold many named keys; if one leaks, rotate that key from the dashboard’s API Keys page or POST /api/credits/tenants/me/keys/KEY_UUID/rotate — the replacement inherits its name, scopes, and expiry, other keys keep working, and without a gracePeriodSeconds overlap the leaked key is dead as of the response.

Prefer a command-line workflow?

Install the official Locus CLI to manage Locus Pro and call the same API from a terminal or agent runtime:

curl -fsSL https://okibi.ai/i/locus/locus | sh
export PATH="${LOCUS_BIN_DIR:-${HOME}/.local/bin}:${PATH}"
locus --help

Use the Locus CLI docs for installation, authentication, command discovery, and agent-friendly JSON output. The repo-backed release targets the production Locus Pro API by default. Keep LOCUS_SECRET_KEY in your secret manager or environment; never pass it in a prompt or commit it to source control.

3. Confirm the available credits

A credit is worth whatever ratio you set, default 1 credit = USD 0.001, so 1,000 credits per US dollar. Evaluation workspaces cannot use earnings payouts until an active commercial agreement is effective.

Dashboard
API

Open Funding & billing → Funding and confirm the available platform balance alongside the top-up controls.

Read the platform balance:

curl "$LOCUS_API/api/credits/balance" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY"
# → { "usd": "0", "credits": "0", ... } for an unfunded workspace

Check the balance any time:

curl "$LOCUS_API/api/credits/balance" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY"
# → { "usd": "0", "credits": "0", "denomination": { "creditsPerDollar": 1000 } }

If the balance is zero, create a pool top-up from Funding & billing → Funding or follow Funding & billing. Credential creation, catalog configuration, and integration previews do not spend credits.

4. Make your first metered call

One prerequisite: ordinary provider entries start disabled, and a call to a disabled endpoint returns 403. Enable tavily/search from Agent tools in the dashboard or with one request:

curl -X PUT "$LOCUS_API/api/credits/catalog/tavily/search" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

Every call has the same shape: POST /api/wrapped/credits/{provider}/{endpoint} with the provider’s own request body. The example below runs a Tavily web search with the SDK and with curl.

// npm install @withlocus/credits
import { LocusCredits } from '@withlocus/credits';

const locus = new LocusCredits(process.env.LOCUS_SECRET_KEY!, {
  baseUrl: 'https://api.paywithlocus.com',
});

const res = await locus.callJson('tavily/search', {
  query: 'latest developments in agent payments',
});

console.log(res.data);          // Tavily's response, verbatim
console.log(res.cost.credits);  // credits charged for THIS call
console.log(res.cost.balance);  // remaining balance

curl -X POST "$LOCUS_API/api/wrapped/credits/tavily/search" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "query": "latest developments in agent payments" }' \
  -i   # -i to see the X-Locus-* headers

No call goes through without an Idempotency-Key. Send a fresh UUID per logical call and reuse it on retries: a retry with the same key replays the stored result and never double-charges. The SDK generates and reuses one for you.

5. Read the cost from the response

The charge and remaining balance come back as response headers; the SDK parses them into res.cost.

Header	`res.cost` field	Meaning
`X-Locus-Credits-Charged`	`cost.credits`	Credits charged for this call
`X-Locus-Credits-Balance`	`cost.balance`	Balance remaining after the charge
`X-Locus-Cost-Usd`	`cost.baseUsd`	Base cost in USD (secret-key calls only)

HTTP/1.1 200 OK
X-Locus-Credits-Charged: 90
X-Locus-Credits-Balance: 9910
X-Locus-Cost-Usd: 0.090000

Secret-key calls with no end-user id charge the base price: 90 credits here on a USD 0.09 base. Add X-Locus-End-User (next section) and the charge becomes your marked-up price instead, 117 credits at a 30% markup. That’s the whole loop: call → charge → balance, with no separate per-call provider invoices to reconcile. Contracted enterprise platform fees are billed separately under the applicable agreement. If a non-streaming upstream call fails before success, Locus releases the reservation automatically. Streaming captures after upstream acceptance and before the first response byte, so later disconnects or stream failures remain charged; see inference and streaming.

Enterprise: charge an end user instead of your pool

To charge a specific end-user at your price instead of drawing from your wholesale pool, add their id:

const res = await locus.call(
  'tavily/search',
  { query: 'agent payments' },
  { user: 'user_123' },   // burns user_123's balance at your price
);

curl -X POST "$LOCUS_API/api/wrapped/credits/tavily/search" \
  -H "Authorization: Bearer $LOCUS_SECRET_KEY" \
  -H "X-Locus-End-User: user_123" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "query": "agent payments" }'

Credits & pricing covers both modes in full.

Next steps

Catalog directory

Browse every API and its pricing model.

Credits & pricing

The exact charge math.

Connect an agent

Use OAuth interactively or a scoped service credential for unattended work.

SDK reference

Server SDK methods and return shapes.

Getting started

Funding & billing

Catalog

Agents

Developer tools

Testing

Personal: connect an agent

Enterprise: make an API call

1. Open or join a workspace

2. Get your keys

Prefer a command-line workflow?

3. Confirm the available credits

4. Make your first metered call

5. Read the cost from the response

Enterprise: charge an end user instead of your pool

Next steps

Catalog directory

Credits & pricing

Connect an agent

SDK reference

​Personal: connect an agent

​Enterprise: make an API call

​1. Open or join a workspace

​2. Get your keys

​Prefer a command-line workflow?

​3. Confirm the available credits

​4. Make your first metered call

​5. Read the cost from the response

​Enterprise: charge an end user instead of your pool

​Next steps

Catalog directory

Credits & pricing

Connect an agent

SDK reference

Personal: connect an agent

Enterprise: make an API call

1. Open or join a workspace

2. Get your keys

Prefer a command-line workflow?

3. Confirm the available credits

4. Make your first metered call

5. Read the cost from the response

Enterprise: charge an end user instead of your pool

Next steps