Sign In

Agent Scope

The agent-scope API is the entry door for one Juglans agent, one API key. Every endpoint in this chapter authenticates with a per-agent bearer token of the form jg_a_… and returns data scoped to that single agent — its identity, its memory, its wallets, its trading state.

This is the layer you wire into:

  • Your own backend that owns or operates a single agent.
  • A juglans-lang program running with [ai.providers.juglans] configured — the lib reads the agent key from juglans.toml and forwards every chat() call through /api/llm/chat/completions.
  • MCP-aware AI tools (Claude Code, Cursor, Codex) connecting via the /mcp transport with the same key.

If you need multi-agent fan-out, end-user partitioning, or company-side rate-limiting, that's the project-scope chapter. If you need to mint agents, manage humans, or rotate OAuth2 clients, that's the platform chapter. Anything an agent itself does — chat, trade, remember, transfer, bridge — lives here.

Mental model

┌────────────────────────────────────────────┐
│  one agent ─── one jg_a_ key ─── all       │
│  endpoints in this chapter                 │
└────────────────────────────────────────────┘

  Authorization: Bearer jg_a_… ──▶  /api/me        (identity)
                                    /api/memory    (kv store)
                                    /api/orders    (trading)
                                    /api/transfers (payouts)
                                    /api/llm/...   (LLM proxy)
                                    /mcp           (MCP)

Every authed call is logged to the agent's audit log via the audit_agent_request middleware — no per-handler bookkeeping needed.

Chapter contents

  • Authentication — header format, audit, error codes, key rotation.
  • Chat & LLM proxy — /api/llm/chat/completions (the OpenAI-compatible endpoint that backs [ai.providers.juglans]), and how it differs from the JWT-only /api/chat.
  • Memory — per-agent KV store, conventional keys (persona, style, rules, goals, expertise).
  • Trading & wallet — /api/me, /api/limits, orders, positions, transfers, bridge, Polymarket setup.
  • MCP — same key, different transport.
  • Reference — compact endpoint table.

Setup — minting a jg_a_* key

Every agent gets one key issued automatically when it's created. To get a key for an existing agent:

From the UI

  1. Open the Juglans app and pick the agent.
  2. Open the Agent Integration panel on the agent profile.
  3. Copy the value labelled API Key — it's the raw jg_a_… token. (We never display it again — copy it now or rotate.)

The same panel shows your MCP URL and one-click downloads for skill.md, openapi.yaml, cursorrules, and gpt-instructions.txt pre-baked with this key.

From the API (JWT-side)

If you'd rather mint programmatically — for example from a setup script — call the platform-side endpoint with your owner JWT:

curl -X POST https://api.juglans.ai/api/agents/{agent_id}/keys \
  -H "Authorization: Bearer <your-jwt>"

Response:

{
  "api_key": "jg_a_3f8a9c1e2d4b5e7f...",
  "api_key_id": "9c2b1f4e-7a3d-4f1c-bd2e-8a4c1f3b9e2a",
  "prefix": "jg_a_3f8a9c1"
}

Save api_key immediately — it is not retrievable later. The prefix is the only thing kept server-side for display purposes.

Test mode

Test-mode agents get a key prefixed jg_a_test_ instead. The test/live distinction is set in the Juglans UI when the agent is created — there is no public API field for it on POST /api/agents. Test-mode keys are accepted by every endpoint in this chapter; trading and transfers run against simulators rather than live exchanges.

Rotating

There is no in-place rotation. To rotate, mint a new key with POST /api/agents/{agent_id}/keys and revoke the old one — the new key is independent and live immediately.