Register an Agent

Register endpoint

POST /v1/agents/register

No authentication required. This is the entry point to the platform.

Request

curl -X POST https://agents.systemr.ai/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "owner_id": "your-unique-owner-id",
    "agent_name": "RiskBot",
    "agent_type": "trading",
    "description": "Equity momentum strategy with strict risk controls",
    "authorized_instruments": ["AAPL", "MSFT", "GOOGL", "AMZN"],
    "authorized_actions": ["size", "risk_check", "analyze"],
    "max_position_size_pct": "5.0",
    "max_daily_loss_pct": "2.0"
  }'

Parameters

Parameter	Type	Required	Description
owner_id	string	Yes	Your unique owner identifier. Used to group agents.
agent_name	string	Yes	Display name for the agent (1 to 100 characters).
agent_type	string	Yes	One of: trading, analysis, risk, composite.
description	string	No	Short description (up to 500 characters).
authorized_instruments	string[]	No	Instrument whitelist. If set, the agent can only trade these symbols.
authorized_actions	string[]	No	Action whitelist. Restricts which tools the agent can call.
max_position_size_pct	string	No	Maximum position size as percentage of equity.
max_daily_loss_pct	string	No	Maximum daily loss as percentage of equity.

Agent types

Type	Use case
trading	Full execution agents. Can connect brokers, place orders, and use all tools.
analysis	Analysis-only agents. Can call analysis and intelligence tools. No broker access.
risk	Risk monitoring agents. Focused on risk checks, compliance, and audit trails.
composite	Multi-purpose agents. Combines capabilities of multiple types.

Response

{
  "agent_id": "agt_a1b2c3d4",
  "agent_name": "RiskBot",
  "agent_type": "trading",
  "mode": "sandbox",
  "api_key": "sr_agent_abc123def456ghi789jkl012mno345pqr678",
  "created_at": "2026-03-25T12:00:00Z"
}

API key format

API keys follow the format sr_agent_ followed by 40 random alphanumeric characters.

• The key is shown once in the registration response.
• Store it securely. It cannot be retrieved after registration.
• Pass it in every request via the X-API-Key header.

Agent modes

New agents start in sandbox mode. You can change the mode later.

Mode	Description
sandbox	Paper trading only. Can connect to the demo broker. No real orders.
live	Real trading. Can connect to any supported broker.
suspended	Temporarily disabled. No API calls permitted.
terminated	Permanently deactivated. Cannot be reactivated.

Change mode with:

curl -X PUT https://agents.systemr.ai/v1/agents/mode \
  -H "X-API-Key: sr_agent_..." \
  -H "Content-Type: application/json" \
  -d '{"mode": "live"}'

SDK registration

import httpx

resp = httpx.post(
    "https://agents.systemr.ai/v1/agents/register",
    json={
        "owner_id": "your-owner-id",
        "agent_name": "MyBot",
        "agent_type": "trading",
    },
)

data = resp.json()
api_key = data["api_key"]  # Store this securely

Multiple agents

One owner can register multiple agents. Each agent has its own:

• API key
• Compute credit balance
• Broker connection
• Audit trail
• Encryption keys

List all agents under your owner:

curl https://agents.systemr.ai/v1/agents/list \
  -H "X-API-Key: sr_agent_..."