API Overview

The Nexgent API provides programmatic access to manage agents, execute trades, and monitor positions.

Base URL

All API requests are made to:

https://your-instance.com/api/v1

For local development:

http://localhost:4000/api/v1

API Versioning

The API uses URL-based versioning. The current version is v1.

/api/v1/agents
/api/v1/trading-signals
/api/v1/wallets

Authentication

The API supports two authentication methods:

Method	Use Case	Header
JWT Token	Dashboard, user sessions	`Authorization: Bearer <access_token>`
API Key	Programmatic access, integrations	`X-API-Key: nex_xxxxx`

Quick Examples

JWT Authentication:

curl -X GET https://your-instance.com/api/v1/agents \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key Authentication:

curl -X POST https://your-instance.com/api/v1/trading-signals \
  -H "X-API-Key: nex_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"tokenAddress": "...", "action": "buy", "score": 4}'

Request Format

Content Type

All requests with a body must use JSON:

Content-Type: application/json

Request Body

{
  "name": "My Agent",
  "tradingMode": "simulation"
}

Response Format

All responses return JSON with consistent structure.

Success Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Agent",
  "tradingMode": "simulation",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

List Response

[
  { "id": "...", "name": "Agent 1", ... },
  { "id": "...", "name": "Agent 2", ... }
]

Error Response

{
  "error": "Agent not found",
  "code": "AGENT_NOT_FOUND"
}

Available Endpoints

Authentication

Endpoint	Description
`POST /auth/register`	Register new user
`POST /auth/login`	Login and get tokens
`POST /auth/refresh`	Refresh access token
`POST /auth/logout`	Logout and invalidate tokens
`GET /auth/me`	Get current user

Agents

Endpoint	Description
`GET /agents`	List all agents
`POST /agents`	Create new agent
`GET /agents/:id`	Get agent by ID
`PUT /agents/:id`	Update agent
`DELETE /agents/:id`	Delete agent
`GET /agents/:id/config`	Get agent trading config
`PUT /agents/:id/config`	Update agent trading config
`GET /agents/:id/performance`	Get agent performance metrics
`GET /agents/:id/balance-history`	Get agent balance history

Agent Resources

Endpoint	Description
`GET /agent-balances`	List agent balances
`GET /agent-positions`	List agent positions
`POST /agent-positions/:id/close`	Close a position
`GET /agent-transactions`	List agent transactions
`GET /agent-historical-swaps`	List historical swaps

Trading Signals

Endpoint	Description
`GET /trading-signals`	List signals
`POST /trading-signals`	Create new signal
`GET /trading-signals/:id`	Get signal by ID
`DELETE /trading-signals/:id`	Delete signal

Wallets

Endpoint	Description
`GET /wallets`	List available wallets
`POST /wallets/assign`	Assign wallet to agent
`POST /wallets/reset`	Reset wallet assignment

API Keys

Endpoint	Description
`GET /api-keys`	List API keys
`POST /api-keys`	Create new API key
`DELETE /api-keys/:id`	Delete API key

Data & Prices

Endpoint	Description
`GET /price-feeds`	Get current prices
`GET /data-sources`	List data sources

Health & Metrics

Endpoint	Description
`GET /health`	Health check
`GET /health/live`	Liveness probe
`GET /health/ready`	Readiness probe
`GET /metrics`	Prometheus metrics

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid input
`401`	Unauthorized - Invalid or missing auth
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`423`	Locked - Account locked
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error

Pagination

List endpoints support pagination via query parameters:

Parameter	Description	Default
`limit`	Number of items to return	50
`offset`	Number of items to skip	0

Example:

GET /api/v1/agents?limit=10&offset=20

Filtering

Many list endpoints support filtering:

# Filter agent balances by agent
GET /api/v1/agent-balances?agentId=550e8400-e29b-41d4-a716-446655440000
 
# Filter transactions by agent
GET /api/v1/agent-transactions?agentId=550e8400-e29b-41d4-a716-446655440000

SDKs & Tools

Postman Collection

A complete Postman collection is available for testing:

Postman Collection

cURL Examples

All documentation includes cURL examples for quick testing.

Exporting Data JWT Tokens