Skip to main content

​
Introduction

The NeuraTrade API is a RESTful API that provides programmatic access to trading analytics, market data, arbitrage opportunities, and autonomous trading features. All endpoints return JSON responses and use standard HTTP response codes.

​
Base URL

The API is accessible at: 
http://localhost:8080
In production environments, replace localhost:8080 with your deployed API URL.

​
API Versioning

All API endpoints are versioned and mounted under the /api/v1 prefix: 
http://localhost:8080/api/v1
Example endpoints:
  • Market data: GET /api/v1/market/prices
  • Arbitrage: GET /api/v1/arbitrage/opportunities
  • User profile: GET /api/v1/users/profile

​
Response Format

All API responses follow a consistent JSON structure:

​
Successful Response

{
  "status": "success",
  "data": {
    // Response payload
  },
  "timestamp": "2026-03-03T10:30:00Z"
}

​
Error Response

{
  "error": "Error message",
  "message": "Detailed error description",
  "code": "ERROR_CODE"
}
​
status
string
Response status: "success" or "error"
​
data
object
Main response payload (present in successful responses)
​
error
string
Error message (present in error responses)
​
message
string
Additional context or description
​
code
string
Machine-readable error code for client handling

​
HTTP Status Codes

The API uses standard HTTP status codes:
Status CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Authentication required or failed
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
409Conflict - Resource already exists
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server-side error
503Service Unavailable - Service temporarily unavailable

​
Error Handling

​
Common Error Codes

​
ADMIN_AUTH_FAILED
string
Admin authentication required for this endpoint
​
INVALID_TOKEN
string
JWT token is invalid or expired
​
RATE_LIMIT_EXCEEDED
string
Rate limit threshold exceeded for your API key or IP address

​
Error Response Example

{
  "error": "Unauthorized",
  "message": "Valid admin API key required for this endpoint",
  "code": "ADMIN_AUTH_FAILED"
}

​
Rate Limiting

The API implements rate limiting to ensure fair usage and system stability.

​
Rate Limit Headers

All API responses include rate limit information in the headers:
​
X-RateLimit-Limit
integer
Maximum number of requests allowed in the current window
​
X-RateLimit-Remaining
integer
Number of requests remaining in the current window
​
X-RateLimit-Reset
integer
Unix timestamp when the rate limit window resets
​
X-RateLimit-Policy
string
Rate limit policy identifier (e.g., "rate_limit_exceeded")

​
Default Limits

  • Default: 100 requests per minute per IP address
  • Authenticated: Higher limits based on subscription tier
  • Admin endpoints: Separate rate limits with higher thresholds

​
Rate Limit Exceeded Response

When rate limits are exceeded, the API returns HTTP 429: 
{
  "error": "Rate limit exceeded",
  "retry_after": 42
}
​
retry_after
integer
Number of seconds to wait before retrying the request
Health check endpoints (/health, /ready, /live) are exempt from rate limiting.

​
Health Check Endpoints

The API provides multiple health check endpoints for monitoring:

​
System Health

GET /health
HEAD /health
Returns overall system health including database, Redis, and CCXT service status.

​
Readiness Check

GET /ready
Indicates if the service is ready to accept traffic.

​
Liveness Check

GET /live
Indicates if the service is running (basic health probe). Health Response Example: 
{
  "status": "healthy",
  "timestamp": "2026-03-03T10:30:00Z",
  "services": {
    "database": "up",
    "redis": "up",
    "ccxt": "up"
  },
  "version": "1.0.0",
  "uptime": "24h15m30s"
}

​
Request Headers

​
Common Headers

​
Authorization
string
required
Bearer token for authenticated endpoints: Bearer <jwt_token>
​
X-API-Key
string
Admin API key for admin-protected endpoints
​
Content-Type
string
default:"application/json"
Request content type (for POST/PUT requests)

​
Pagination

Endpoints returning lists support pagination through query parameters:
​
limit
integer
default:"50"
Number of items to return (max 100)
​
offset
integer
default:"0"
Number of items to skip
Paginated Response Example: 
{
  "data": [
    // ... items
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 150
  }
}

​
Environment-Specific Behavior

In production environments (ENVIRONMENT=production or GIN_MODE=release), stricter security validations are enforced:
  • Admin API keys must be explicitly configured
  • JWT secrets must be at least 32 characters
  • Default or example credentials are rejected

​
Next Steps

Authentication

Learn about JWT tokens and API key authentication

Market Data

Access real-time market prices and orderbook data

Arbitrage

Discover arbitrage opportunities across exchanges

Trading

Execute trades and manage positions

Build docs developers (and LLMs) love

Get started for freeTalk to us