Getting Started

Computalot is built for agents and programmatic access. Authenticate with an admin-issued API key or an admin-whitelisted wallet session, inspect billing truth, fund with x402 when needed, and start running compute. Pick the path that fits your use case.

Path 1: Use a Sealed Recipe

Sealed recipes are platform-provided compute primitives. No project setup needed — just send a typed payload and get results.

Prerequisites

export BASE_URL="https://computalot.com"
export TOKEN="flk_..."   # Admin-issued API key or allowlisted wallet session

Before your first submission, check GET /api/v1/account/balance, GET /api/v1/account/holds, GET /api/v1/account/ledger, and GET /api/v1/account/quotes so you know the account’s billing truth and any open funding or shortfall quotes.

Step 1: Browse available recipes

curl -sS "$BASE_URL/api/v1/recipes" \
  -H "Authorization: Bearer $TOKEN"

Step 2: Submit a recipe job

curl -sS "$BASE_URL/api/v1/recipes/packing/jobs" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "operation": "eval",
      "candidate": [0.12, 0.31, 0.88, 0.45, 0.67, 0.23, 0.91, 0.14, 0.56, 0.78, 0.33, 0.62, 0.85, 0.19, 0.44, 0.71, 0.28, 0.93, 0.16, 0.59, 0.82, 0.37, 0.65, 0.11, 0.48, 0.74, 0.26, 0.89, 0.52, 0.18, 0.69, 0.41, 0.95, 0.32, 0.76, 0.22, 0.58, 0.84, 0.13, 0.47, 0.73, 0.39, 0.66, 0.21, 0.87]
    },
    "timeout_s": 300
  }'

Step 3: Read results

curl -sS "$BASE_URL/api/v1/results/<job_id>" \
  -H "Authorization: Bearer $TOKEN"

That’s it. See the full Recipe Catalog for all available recipes and their operations.

Path 2: Run Your Own Code

Create a sandboxed project, upload your code, and submit custom jobs.

Prerequisites

export BASE_URL="https://computalot.com"
export TOKEN="flk_..."   # Admin-issued API key or allowlisted wallet session

If you don’t have a token yet, see Authentication for the beta access model and waitlist path.

Billing truth for this same token lives on GET /api/v1/account/balance, GET /api/v1/account/holds, GET /api/v1/account/ledger, and GET /api/v1/account/quotes.

Step 1: Create a project

curl -sS "$BASE_URL/api/v1/projects" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "remote_dir": "/root/my-project"
  }'

Step 2: Write your code

Your project needs at minimum a setup script and your code. See Projects for the full setup guide.

# job.py
import json, os
 
payload = json.load(open(os.environ["COMPUTALOT_TASK_PAYLOAD"]))
print(f"Processing: {payload}")
 
result = {"status": "ok", "input": payload}
json.dump(result, open(os.environ["COMPUTALOT_TASK_RESULT"], "w"))

Step 3: Upload your project

tar czf code.tar.gz Dockerfile computalot.project.json job.py
 
curl -sS "$BASE_URL/api/v1/projects/my-project/push" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @code.tar.gz

After a successful push, the latest revision is published immediately. You can submit jobs right away; the first one may take longer while Computalot prepares runtime capacity on demand.

Optional: if you want to prepare currently available workers ahead of time, call init manually:

curl -sS "$BASE_URL/api/v1/projects/my-project/init" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

If project init returns 402 Payment Required with a shortfall quote, fund the account and retry the same POST /api/v1/projects/my-project/init request.

Step 4: Submit a job

curl -sS "$BASE_URL/api/v1/jobs" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "structured_runner",
    "runner_command": ["python3", "job.py"],
    "payload": {"test": true},
    "project": "my-project",
    "timeout_s": 120
  }'

If job submit returns 402 Payment Required with a shortfall quote, fund the account and retry the same submit request.

Check GET /api/v1/projects/my-project/status if you want to inspect whether the revision is merely published (can_accept_new_jobs: true, ready_for_jobs: false) or already warm (ready_for_jobs: true).

Step 5: Read results

curl -sS "$BASE_URL/api/v1/results/<job_id>" \
  -H "Authorization: Bearer $TOKEN"