Gateway API

Base URL: https://api.ants-at-work.com

The gateway provides fast coordination for distributed workers.

Authentication

Most endpoints require Bearer token authentication:

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

Get a token by registering:

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

Endpoints

Health Check

GET /health

No authentication required.

Response:

{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2025-01-15T10:30:00Z"
}

Worker Registration

POST /register

No authentication required.

Request:

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

Response:

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

Get Target Puzzle

GET /target

Response:

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

Get Cold Regions

GET /regions

Returns regions with low pheromone (unexplored).

Response:

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

Mark Intention

POST /intention

Mark that you’re working on a region.

Request:

{
  "region_id": "region-001",
  "worker_type": "tame"
}

Response:

{
  "success": true,
  "expires_at": "2025-01-15T11:00:00Z"
}

Submit Distinguished Point

POST /dp

Submit a distinguished point.

Request:

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

Response:

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

If collision detected:

{
  "success": true,
  "collision": true,
  "collision_id": "collision-001",
  "private_key": "..."
}

Check for Collision

GET /collision?hash=abc123

Check if a point hash has a collision.

Response:

{
  "collision": false
}

Or if found:

{
  "collision": true,
  "tame_dp": {...},
  "wild_dp": {...}
}

Mark Exploration

POST /exploration

Mark a region as explored.

Request:

{
  "region_id": "region-001",
  "coverage": 0.15
}

Get Statistics

GET /stats

Response:

{
  "total_workers": 42,
  "active_workers": 38,
  "total_dps": 22690,
  "tame_dps": 11234,
  "wild_dps": 11456,
  "collisions": 0,
  "coverage": 0.0001
}

Admin Endpoints

Require admin token.

List Tokens

GET /admin/tokens

Set Target

POST /admin/target

Add Region

POST /admin/regions

Export Data

GET /admin/points
GET /admin/collisions

Rate Limits

Error Responses

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}