← Back to ClawdPool

ClawdPool API

Automated liquidity pool spawning at your fingertips

Base URL: https://api.clawdpool.io
Authentication: API key required in x-api-key header

🔐 Authentication

All API requests require an API key. Include it in the request headers:

x-api-key: your_api_key_here

To get an API key, join our Discord.

⚠️ Keep your API key secret! Never commit it to public repositories or share it publicly.

📡 Endpoints

POST /api/spawn

Queue a new pool spawn. Create genesis pools that automatically spawn children when volume thresholds are hit.

Request Body

Field Type Required Description
source string Yes Source of request: "twitter", "tag", "api", "manual"
userId string Yes User identifier
token0 address Yes First token address (0x...)
token1 address Yes Second token address (0x...)
initialLiquidity0 string Yes Initial liquidity for token0 (in token units)
initialLiquidity1 string Yes Initial liquidity for token1 (in token units)
spawnThreshold string Yes Volume threshold to trigger child pool spawn
feeBps number No Fee in basis points (default: 300 = 0.3%)
chain string No "base", "unichain", or "arbitrum" (default: "base")
metadata object No Additional metadata (twitterHandle, tagId, referrer)

Example Request

curl -X POST https://api.clawdpool.io/api/spawn \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "source": "api",
    "userId": "user123",
    "token0": "0x4200000000000000000000000000000000000006",
    "token1": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "initialLiquidity0": "1000",
    "initialLiquidity1": "1000",
    "spawnThreshold": "10000",
    "feeBps": 300,
    "chain": "base"
  }'

Response

{
  "success": true,
  "jobId": "spawn-1234567890-abc123",
  "message": "Pool spawn queued successfully",
  "estimatedTime": "30-60 seconds"
}

GET /api/spawn/:jobId

Check the status of a pool spawn job. Track your pool deployment in real-time.

Example Request

curl -X GET https://api.clawdpool.io/api/spawn/spawn-1234567890-abc123 \
  -H "x-api-key: your_api_key"

Response

{
  "jobId": "spawn-1234567890-abc123",
  "status": "completed",
  "progress": 100,
  "data": {
    "request": { ... }
  },
  "result": {
    "success": true,
    "poolId": 42,
    "factoryAddress": "0x...",
    "transactionHash": "0x...",
    "gasUsed": "250000"
  },
  "attemptsMade": 1,
  "processedOn": 1234567890,
  "finishedOn": 1234567950
}

Status Values

POST /api/transfer

Queue a token transfer. Send tokens to any address on supported chains.

Request Body

Field Type Required Description
recipient address Yes Recipient address (0x...)
token address Yes Token address (0x...)
amount string Yes Amount to transfer (in token units)
chain string Yes "base", "unichain", or "arbitrum"
source string Yes "twitter", "tag", or "api"
metadata object No Additional metadata (twitterHandle, reason)

Example Request

curl -X POST https://api.clawdpool.io/api/transfer \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "100",
    "chain": "base",
    "source": "api",
    "metadata": {
      "reason": "reward"
    }
  }'

Response

{
  "success": true,
  "jobId": "transfer-123",
  "message": "Transfer queued successfully",
  "estimatedTime": "30-60 seconds"
}

GET /api/status

Get queue statistics. Monitor system health and queue status.

Example Request

curl -X GET https://api.clawdpool.io/api/status \
  -H "x-api-key: your_api_key"

Response

{
  "success": true,
  "timestamp": 1234567890,
  "queues": {
    "poolSpawn": {
      "waiting": 5,
      "active": 2,
      "completed": 100,
      "failed": 1,
      "delayed": 0
    },
    "transfer": {
      "waiting": 3,
      "active": 1,
      "completed": 50,
      "failed": 0,
      "delayed": 0
    }
  }
}

⏱️ Rate Limits

The API is rate limited to 100 requests per minute per IP address. If you exceed this limit, you'll receive a 429 Too Many Requests response.

💡 Tip: For high-volume applications, contact us on Discord to discuss higher rate limits.

❌ Error Responses

All errors follow this format:

{
  "error": "Error message describing what went wrong",
  "details": [ /* optional array of validation errors */ ]
}

Common Error Codes

Code Meaning
400 Bad Request - Invalid request data
401 Unauthorized - Missing API key
403 Forbidden - Invalid API key
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong on our end

🔔 Webhooks (Coming Soon)

Soon you'll be able to register webhook URLs to receive notifications when:

💬 Need Help?

Join our Discord for support, or check out the GitHub repo.

🦀 Rack 'em up! 🦀