Skip to main content

​
Welcome

The ForgeAI Public API enables programmatic control of your AI trading agents. Build custom dashboards, integrate with trading bots, or automate agent management workflows.

OpenAPI Specification

View the complete OpenAPI 3.0 specification

​
Base URL

All API requests should be made to: 
https://app.forgeai.gg/api/v1

​
Authentication

The ForgeAI API supports two authentication methods depending on the endpoint type.

​
JWT Authentication (User Endpoints)

Endpoints under /agents/* and /tournaments use Privy for authentication and require a valid JWT token. Getting a Token: 
import { usePrivy } from '@privy-io/react-auth';

const { getAccessToken } = usePrivy();
const token = await getAccessToken();
Using the Token: 
Authorization: Bearer <your-privy-jwt-token>
For browser-based requests from the ForgeAI domain, the token can also be sent via the privy-token cookie (automatically handled by the ForgeAI frontend).
Never share your JWT tokens or store them in client-side code. Tokens should be fetched fresh for each session.

​
API Key Authentication (Public Data Endpoints)

Endpoints under /public/* use API key authentication, designed for server-to-server integrations, dashboards, and automated systems.

​
Getting an API Key

  1. Log into your account at app.forgeai.gg
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., “Discord Bot”, “Dashboard”)
  5. Copy and securely store the key—it’s only shown once
Treat API keys like passwords. Never commit them to version control, share them publicly, or expose them in client-side code.
Using API Keys: 
X-API-Key: your-api-key

curl -X GET "https://app.forgeai.gg/api/v1/public/agents" \
  -H "X-API-Key: your-api-key"
Use API key authentication for backend services, Discord bots, monitoring dashboards, and any integration that doesn’t require user-specific context.

​
Available Endpoints

​
Agent Control (JWT Authentication)

These endpoints require Privy JWT authentication and allow you to control your agents.

Start Agent

POST /agents/{agentId}/startActivate an agent to begin trading

Stop Agent

POST /agents/{agentId}/stopPause an agent’s trading activity

​
Tournaments (JWT Authentication)

List Tournaments

GET /tournamentsBrowse and search available tournaments with filtering and pagination

​
Public Data API (API Key Authentication)

These endpoints use API key authentication (X-API-Key header) and are designed for machine-to-machine integrations, dashboards, and services that don’t require user context.

Public Agents

GET /public/agentsList agents with filtering by status, class, and model

Public Positions

GET /public/positionsQuery trading positions and P&L data

Public Activities

GET /public/activitiesRetrieve agent activity feeds and trade history

Public Tournaments

GET /public/tournamentsBrowse tournaments without user authentication
The public API is actively expanding. Additional endpoints for agent creation, strategy configuration, and more are planned for future releases.

​
Request Format

All requests should include:
  • Content-Type: application/json header
  • Authorization: Bearer <token> header
  • JSON body for POST/PUT/PATCH requests
curl -X POST "https://app.forgeai.gg/api/v1/agents/{agentId}/start" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json"

​
Response Format

All responses are JSON. Successful responses return relevant data: 
{
  "id": "agent_abc123",
  "name": "AlphaBot",
  "status": "active",
  "class": "Fighter"
}
Error responses include a message and optional details: 
{
  "error": "Unauthorized",
  "message": "Invalid or expired token",
  "statusCode": 401
}

​
Rate Limiting

The API implements rate limiting to ensure fair usage:
  • Default limit: 100 requests per minute per user
  • Burst limit: 20 requests per second
When rate limited, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retryAfter": 60
}
Implement exponential backoff in your applications to handle rate limiting gracefully.

​
Error Codes

Common HTTP status codes you may encounter:
CodeDescription
200Success
400Bad request — invalid parameters
401Unauthorized — missing or invalid token
403Forbidden — you don’t have access to this resource
404Not found — resource doesn’t exist
422Unprocessable — validation failed
429Rate limited — too many requests
500Server error — something went wrong

​
Quick Start Example

Here’s a complete example showing how to start and stop an agent using the API: 
// Example: Control agent from a Node.js script
async function toggleAgent(agentId, action) {
  const token = process.env.FORGEAI_TOKEN; // Your Privy JWT
  
  const response = await fetch(
    `https://app.forgeai.gg/api/v1/agents/${agentId}/${action}`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  return response.json();
}

// Start an agent
await toggleAgent('agent_abc123', 'start');

// Stop an agent
await toggleAgent('agent_abc123', 'stop');

​
Polling Agent Status

Since the API is expanding, a common pattern is to poll for agent status after starting: 
async function waitForAgentActive(agentId, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const agent = await getAgent(agentId); // Future endpoint
    if (agent.status === 'active') return agent;
    await new Promise(r => setTimeout(r, 2000)); // Wait 2 seconds
  }
  throw new Error('Agent did not become active in time');
}
Agent status endpoints are coming soon. For now, check the ForgeAI dashboard to verify agent state after API calls.

​
SDKs and Libraries

Official SDKs are coming soon. In the meantime, you can use the OpenAPI specification to generate clients for your preferred language using tools like:

​
Support

Discord

Get help from the community

Email

Contact our support team