Skip to main content
Documentation API Reference

API Reference

Gateway API for the Ants at Work Colony

Base URL

https://api.ants-at-work.com
Check Status
Public Endpoints Trading Endpoints (Public) Hunt BTC Endpoints Trading Endpoints (Authenticated) Member Endpoints Admin Endpoints Authentication Rate Limits Errors

Authentication

Most endpoints require Bearer token authentication. Include your token in the Authorization header: 

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.ants-at-work.com/regions

Getting a Token

Register a worker to receive a token. Tokens are valid for 30 days and can be refreshed. 

curl -X POST https://api.ants-at-work.com/register \
  -H "Content-Type: application/json" \
  -d '{"hostname":"my-worker","gpu":"RTX4090","platform":"linux"}'

Public Endpoints

No authentication required. Read-only access to colony statistics and data.

GET /health

Health check endpoint

Response

{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2026-01-21T10:30:00Z"
}
POST /register

Worker self-registration (returns token)

Request Body

{
  "hostname": "my-laptop",
  "platform": "darwin",
  "gpu": "M2 Max"
}

Response

{
  "token": "abc123...",
  "worker_id": "worker-xyz",
  "gateway_url": "https://api.ants-at-work.com"
}
GET /public/stats

Colony statistics (workers, points, collisions)

Response

{
  "total_workers": 42,
  "active_workers": 38,
  "total_dps": 22690,
  "collisions": 0,
  "coverage": 0.0001
}
GET /public/regions

Region pheromone data

Response

{
  "regions": [
    {
      "id": "region-001",
      "start": "400000000000000000",
      "end": "400010000000000000",
      "pheromone": 0.1,
      "workers_active": 0
    }
  ]
}
GET /public/graph

Graph visualization data (nodes, edges)

GET /public/activity

Real-time activity stream

Trading Endpoints (Public)

Read-only access to trading statistics and market data.

GET /public/trading/stats

Trading statistics (win rate, PnL, equity)

Response

{
  "win_rate": 0.526,
  "total_pnl": 1234.56,
  "equity": 10000.00,
  "trades_today": 12,
  "active_patterns": 42
}
GET /public/trading/positions

Open positions

Response

{
  "positions": [
    {
      "symbol": "BTC-PERP",
      "direction": "long",
      "size": 0.05,
      "entry_price": 96000,
      "unrealized_pnl": 125.50
    }
  ]
}
GET /public/trading/trades

Recent closed trades

GET /public/trading/signals

Recent trading signals

GET /public/trading/regimes

Regime history

GET /public/trading/edges

Pheromone trails (signal edges)

Parameters

Name Type Required Default
limit number No 50
GET /public/trading/equity

Equity curve data

Hunt BTC Endpoints Auth Required

Authenticated endpoints for the Hunt BTC mission. Requires Bearer token.

GET /target

Get current puzzle target

Response

{
  "puzzle_id": "puzzle-71",
  "bit_length": 71,
  "target_address": "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU",
  "target_pubkey": "04b...",
  "range_start": "400000000000000000",
  "range_end": "7ffffffffffffffffff"
}
GET /regions

Get cold regions (low pheromone)

POST /dp

Deposit distinguished point (encrypted)

Request Body

{
  "hash": "abc123...",
  "worker_type": "tame",
  "point_hex": "04...",
  "distance_encrypted": "..."
}

Response

{
  "success": true,
  "collision": false,
  "dp_id": "dp-123"
}
POST /intention

Mark working intention on a region

Request Body

{
  "region_id": "region-001",
  "worker_type": "tame"
}
POST /exploration

Mark exploration progress

Request Body

{
  "region_id": "region-001",
  "coverage": 0.15
}
GET /collision

Check for collision

Parameters

Name Type Required Default
hash string Yes -
GET /stats

Get worker statistics

GET /status

Check token status

POST /refresh

Refresh token (extend 30 days)

Trading Endpoints (Authenticated) Auth Required

Write endpoints for the trading system. Requires Bearer token.

POST /trading/stats

Update trading statistics

POST /trading/trade

Add or update a trade

Request Body

{
  "id": "trade-001",
  "symbol": "BTC-PERP",
  "direction": "long",
  "entry_price": 96000,
  "size": 0.05,
  "entry_time": 1705000000000,
  "is_open": true
}
POST /trading/signal

Add a trading signal

POST /trading/regime

Add regime change

POST /trading/edge

Update signal edge (pheromone)

Request Body

{
  "id": "BTC-PERP:bull:normal:neutral:long",
  "from_state_id": "BTC-PERP:bull:normal:neutral",
  "to_direction": "long",
  "trail_pheromone": 12.5,
  "win_count": 45,
  "loss_count": 30
}
POST /trading/edges/batch

Batch update edges

Member Endpoints

Member registration and profile management.

POST /member/register

Register new member

GET /member/:username

Get member profile

POST /member/lookup

Lookup by email

POST /member/:id/trust

Add trust to member

Admin only

GET /member/:id/trust

Get trust history

GET /members/stats

Member statistics

Admin Endpoints Auth Required

Administrative operations. Requires admin token.

GET /admin/tokens

List all tokens

DELETE /admin/tokens/:id

Revoke a token

POST /admin/target

Set puzzle target

POST /admin/regions

Add region

GET /admin/points

List DPs (distances protected)

GET /admin/collisions

List collisions

DELETE /admin/points

Clear all points

GET /admin/security

Security status

POST /admin/security/revoke-all

Emergency revoke all tokens

POST /admin/trading/reset

Reset trading data

Rate Limits

Endpoint Limit
/register 10/hour per IP
/dp 100/minute per worker
/regions 60/minute per worker
Others 120/minute per worker

Error Responses

Error Format

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}
Status Code Meaning
400 Bad request - Invalid parameters or body
401 Unauthorized - Invalid or expired token
403 Forbidden - Insufficient permissions
429 Rate limited - Too many requests
500 Server error - Internal error

SDKs and Tools

Python SDK

Install the ants-worker package to interact with the API from Python.

pip install ants-worker

Troubleshooting

Common issues and solutions when working with the Gateway API.

Back to Documentation