API Reference

REST API reference for programmatic access to COD3X. Authenticate, manage agents, execute trades, and query performance data.

RESTAPI

WebSocketFeeds

JWTAuth

Rate LimitedAccess

Authentication

All API requests require a valid JWT token obtained through the authentication flow. Include the token in the Authorization header.

BASH

bash

1# 1. Sign in to get a JWT token
2curl -X POST https://api.cod3x.io/auth/login \
3  -H "Content-Type: application/json" \
4  -d '{"email": "user@example.com", "password": "your-password"}'
5 
6# Response: { "token": "eyJhbG...", "refreshToken": "..." }
7 
8# 2. Use the token in subsequent requests
9curl https://api.cod3x.io/agents \
10  -H "Authorization: Bearer eyJhbG..."
11 
12# 3. Refresh token before expiry (tokens expire in 1 hour)
13curl -X POST https://api.cod3x.io/auth/refresh \
14  -H "Content-Type: application/json" \
15  -d '{"refreshToken": "..."}'

Wallet Authentication

For Web3 authentication, use the SIWE (Sign-In with Ethereum) flow. Sign a message with your wallet, then exchange the signature for a JWT token via the /auth/siwe endpoint.

Endpoints Overview

The API is organized into logical endpoint groups. All endpoints use JSON request/response bodies.

Group	Base Path	Description	Auth
Authentication	/auth/*	Login, signup, refresh tokens, SIWE	Public
Agents	/agents/*	Create, configure, start/stop agents	Required
Trading	/trading/*	Place orders, manage positions, trade history	Required
Portfolio	/portfolio/*	Wallet balances, deposits, withdrawals	Required
Arena	/arena/*	Competitions, leaderboards, agent rankings	Optional
Analytics	/analytics/*	Performance metrics, P&L, trade history	Required
Chat	/chat/*	AI assistant messages, conversation history	Required
Goals	/goals/*	Create, manage, and monitor agent goals	Required

Example Requests

List Your Agents

BASH

bash

1curl https://api.cod3x.io/agents \
2  -H "Authorization: Bearer $TOKEN"
3 
4# Response
5{
6  "agents": [
7    {
8      "id": "agent-123",
9      "name": "Alpha Trader",
10      "status": "active",
11      "strategy": "momentum",
12      "created_at": "2024-01-15T10:00:00Z"
13    }
14  ]
15}

Get Agent Performance

BASH

bash

1curl https://api.cod3x.io/analytics/agent-123/performance?period=30d \
2  -H "Authorization: Bearer $TOKEN"
3 
4# Response
5{
6  "total_return": 24.6,
7  "sharpe_ratio": 1.85,
8  "max_drawdown": -8.3,
9  "win_rate": 68.2,
10  "total_trades": 156,
11  "profit_factor": 2.1
12}

Place a Manual Order

BASH

bash

1curl -X POST https://api.cod3x.io/trading/orders \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "agent_id": "agent-123",
6    "symbol": "BTC-PERP",
7    "side": "buy",
8    "type": "limit",
9    "size": 0.1,
10    "price": 42000,
11    "leverage": 10
12  }'

WebSocket Events

Connect to the WebSocket endpoint for real-time updates. Authenticate with your JWT token on connection.

JAVASCRIPT

javascript

1import { io } from "socket.io-client";
2 
3const socket = io("wss://api.cod3x.io", {
4  auth: { token: "your-jwt-token" }
5});
6 
7socket.on("trade.executed", (data) => {
8  console.log("Trade:", data.symbol, data.side, data.price);
9});
10 
11socket.on("position.updated", (data) => {
12  console.log("Position:", data.symbol, "PnL:", data.unrealized_pnl);
13});

Event	Payload	Description
trade.executed	{ symbol, side, price, size, pnl }	Trade was executed by agent
position.updated	{ symbol, size, entry, mark, pnl }	Position state changed
goal.triggered	{ goal_id, trigger, action }	Goal condition was met
agent.status	{ agent_id, status, reason }	Agent started/stopped/errored
balance.changed	{ wallet, balance, change }	Wallet balance updated
alert.fired	{ type, message, severity }	Price or event alert triggered

Rate Limits

Tier	Requests/Min	WebSocket Connections	Notes
Free	60	1	Basic access
OPERATOR	120	3	CDX staking tier 1
ARCHITECT	300	5	CDX staking tier 2
SENTINEL	600	10	CDX staking tier 3

TIP

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset. Use these to implement backoff in your integrations.

Error Handling

Status Code	Meaning	Common Cause
400	Bad Request	Invalid parameters or malformed JSON
401	Unauthorized	Missing or expired JWT token
403	Forbidden	Insufficient permissions or tier
404	Not Found	Resource doesn't exist
429	Rate Limited	Too many requests, slow down
500	Server Error	Internal error, retry with backoff

JSON

json

1{
2  "error": {
3    "code": "INSUFFICIENT_MARGIN",
4    "message": "Not enough margin to open position. Required: $1,234.56, Available: $567.89",
5    "details": {
6      "required_margin": 1234.56,
7      "available_margin": 567.89
8    }
9  }
10}

Glossary

API and trading terminology

Troubleshooting

Common issues and solutions

Security

Authentication and key management

Was this helpful?

PreviousGlossaryREFERENCE NextSecurityREFERENCE

1# 1. Sign in to get a JWT token

2curl -X POST https://api.cod3x.io/auth/login \

3 -H "Content-Type: application/json" \

4 -d '{"email": "user@example.com", "password": "your-password"}'

6# Response: { "token": "eyJhbG...", "refreshToken": "..." }

8# 2. Use the token in subsequent requests

9curl https://api.cod3x.io/agents \

10 -H "Authorization: Bearer eyJhbG..."

12# 3. Refresh token before expiry (tokens expire in 1 hour)

13curl -X POST https://api.cod3x.io/auth/refresh \

14 -H "Content-Type: application/json" \

15 -d '{"refreshToken": "..."}'

Group

Base Path

Description

Auth

Authentication

/auth/*

Public

Agents

/agents/*

Create, configure, start/stop agents

Required

Trading

/trading/*

Place orders, manage positions, trade history

Required

Portfolio

/portfolio/*

Wallet balances, deposits, withdrawals

Required

Arena

/arena/*

Competitions, leaderboards, agent rankings

Optional

Analytics

/analytics/*

Performance metrics, P&L, trade history

Required

Chat

/chat/*

AI assistant messages, conversation history

Required

Goals

/goals/*

Create, manage, and monitor agent goals

Required

1curl https://api.cod3x.io/agents \

2 -H "Authorization: Bearer $TOKEN"

4# Response

5{

6 "agents": [

7 {

8 "id": "agent-123",

9 "name": "Alpha Trader",

10 "status": "active",

11 "strategy": "momentum",

12 "created_at": "2024-01-15T10:00:00Z"

13 }

14 ]

15}

1curl https://api.cod3x.io/analytics/agent-123/performance?period=30d \

2 -H "Authorization: Bearer $TOKEN"

4# Response

5{

6 "total_return": 24.6,

7 "sharpe_ratio": 1.85,

8 "max_drawdown": -8.3,

9 "win_rate": 68.2,

10 "total_trades": 156,

11 "profit_factor": 2.1

12}

1curl -X POST https://api.cod3x.io/trading/orders \

2 -H "Authorization: Bearer $TOKEN" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "agent_id": "agent-123",

6 "symbol": "BTC-PERP",

7 "side": "buy",

8 "type": "limit",

9 "size": 0.1,

10 "price": 42000,

11 "leverage": 10

12 }'

1import { io } from "socket.io-client";

3const socket = io("wss://api.cod3x.io", {

4 auth: { token: "your-jwt-token" }

5});

7socket.on("trade.executed", (data) => {

8 console.log("Trade:", data.symbol, data.side, data.price);

9});

11socket.on("position.updated", (data) => {

12 console.log("Position:", data.symbol, "PnL:", data.unrealized_pnl);

13});

Event

Payload

Description

trade.executed

{ symbol, side, price, size, pnl }

Trade was executed by agent

position.updated

{ symbol, size, entry, mark, pnl }

Position state changed

goal.triggered

{ goal_id, trigger, action }

Goal condition was met

agent.status

{ agent_id, status, reason }

Agent started/stopped/errored

balance.changed

{ wallet, balance, change }

Wallet balance updated

alert.fired

{ type, message, severity }

Price or event alert triggered

Tier

Requests/Min

WebSocket Connections

Notes

Free

Basic access

OPERATOR

120

CDX staking tier 1

ARCHITECT

300

CDX staking tier 2

SENTINEL

600

CDX staking tier 3

Status Code

Meaning

Common Cause

400

Bad Request

Invalid parameters or malformed JSON

401

Unauthorized

Missing or expired JWT token

403

Forbidden

Insufficient permissions or tier

404

Not Found

Resource doesn't exist

429

Rate Limited

Too many requests, slow down

500

Server Error

Internal error, retry with backoff

1{

2 "error": {

3 "code": "INSUFFICIENT_MARGIN",

4 "message": "Not enough margin to open position. Required: $1,234.56, Available: $567.89",

5 "details": {

6 "required_margin": 1234.56,

7 "available_margin": 567.89

8 }

9 }

10}