Spider Docs

Two ways to use Spider:

Base URL:
https://api.spidernetwork.ai

Three steps from zero to your first completion:

1. Get an API key. Sign in → API Keys → Create key. The full key (spk_<id>.<secret>) is shown once — store it somewhere safe.

2. Add credits. Dashboard → Usage & Billing → add test credits (up to $100 per top-up). Jobs are rejected with 402 when your balance is zero.

3. Submit and poll. Inference is asynchronous: create a job, then poll it until it finishes (typically well under a second of queue time plus model generation time).

# Create a job
curl -X POST "https://api.spidernetwork.ai/v1/jobs" \
  -H "Authorization: Bearer spk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-job-001" \
  -d '{
    "model": "llama3.2:3b",
    "input": {
      "messages": [
        { "role": "user", "content": "Explain spider silk in one sentence." }
      ]
    }
  }'
# → 202 { "jobId": "9be5…" }

# Poll until SUCCEEDED
curl "https://api.spidernetwork.ai/v1/jobs/9be5…" \
  -H "Authorization: Bearer spk_YOUR_KEY"

Every request carries your API key as a bearer token: Authorization: Bearer spk_<id>.<secret>.

Keys are minted and revoked in the dashboard. The secret is hashed at rest — if you lose it, revoke the key and mint a new one. Each key belongs to your account: its jobs debit your balance and appear in your usage history, and you can only read jobs created with your own keys.

POST /v1/jobs — returns 202 Accepted with a jobId.

GET /v1/jobs/:jobId — returns the job's current state. Poll every 1–2 seconds until SUCCEEDED or FAILED.

{
  "id": "9be5…",
  "model": "llama3.2:3b",
  "status": "SUCCEEDED",
  "createdAt": "2026-08-03T16:11:00.345Z",
  "updatedAt": "2026-08-03T16:11:01.137Z",
  "security": { "tier": "COMMUNITY", "match": "MINIMUM" },
  "result": {
    "output": "Spider silk is a protein fiber…",
    "usage": { "inputTokens": 26, "outputTokens": 39, "durationMs": 433 }
  }
}

result.usage is what you are billed on. Failed jobs carry failure: { code, message } instead of a result and are never billed.

Reliability is the scheduler's job, not yours: if a node goes offline mid-job, Spider detects the lost lease and re-runs the job on other capacity automatically. Your idempotency key protects the create call; the network protects execution.

Jobs run on community GPUs first — always. Models with a serverless backstop never wait for capacity: when no community node is available the job executes on AWS Bedrock within milliseconds. Community-only models queue until a capable node frees up.

Note: the backstop currently serves llama3.2 requests with Llama 3.1 8B (the small 3.2 checkpoints were retired by the provider) — a strictly stronger model at the same price to you.

Tiers are a hard scheduling constraint, never a preference: a job is only ever placed on hardware that satisfies its tier.

match: "MINIMUM" (default) accepts the requested tier or stronger. match: "EXACT" pins the exact tier — e.g. EXACT COMMUNITY guarantees your job never leaves community hardware. If no online capacity satisfies the tier, the job stays QUEUED rather than silently degrading.

Simple, flat, per-token. Same price on every model and every tier. You are billed only for jobs that succeed, on the exact usage the serving hardware reports.

What that means in practice:

Billing is prepaid: jobs are accepted while your balance is positive. Amounts are tracked in micro-dollars, so even a $5 top-up covers roughly 4,500 typical chat messages. During the sandbox phase credits are simulated test credits — no real money moves yet.

Any reasonably modern machine with a GPU (or Apple Silicon) can serve inference and earn. Requirements:

• NVIDIA GPU with 4 GB+ VRAM, or Apple Silicon with 8 GB+ RAM
• macOS, Windows, or Linux; a stable internet connection
• Ollama (the installer sets it up on Linux, and via Homebrew on macOS if available)

Setup takes one command. Sign in → Nodes → Add node. The dashboard detects your OS and generates a paste-ready command with a single-use pairing code (valid 30 minutes):

curl -fsSL https://<site>/install.sh | sh -s -- \
  --endpoint <url> --api-key <key> --code SPIDER-XXXX-XXXX

The agent then handles everything:

• Hardware scan — detects your GPU and computes a VRAM budget (discrete GPU: VRAM minus 1 GB headroom; Apple Silicon: half of system RAM)
• Auto model install — pulls every recommended model your budget can run well, in the background, and advertises each one as it lands
• Goes online — heartbeats every 30 seconds and starts receiving jobs

Your machine stays yours: the agent only talks outbound (no open ports), runs models through your local Ollama, and Ollama unloads models after ~5 minutes idle — so gaming and daily use are unaffected when no jobs are flowing.

Node owners earn 70% of every job their machine serves, credited per job the moment it completes:

The scheduler always prefers community nodes over the platform backstop, so if your machine is online and capable, it gets the work. What that adds up to depends on demand routed to you and your hardware's throughput. Honest ballparks, assuming a typical chat mix (~3 input tokens per output token):

"While serving" = revenue while actively generating (output at $2.10/1M plus the input share). "% busy" = fraction of the month your node spends serving jobs, which depends entirely on network demand — early on expect the low end. Electricity is on you: a 4090 at full tilt draws ~450W (~$0.07/hr at $0.15/kWh), so serving is profitable whenever jobs flow. These figures are estimates at current pricing, not guarantees.

Earnings accrue to your balance in real time — watch them in Earnings in the dashboard, per node and per job. Payouts are simulated during the sandbox phase (one click, zeroes your earned balance into the payout ledger); real payouts via Stripe are the launch plan.

Pause / resume: stop the agent process (Ctrl-C or kill). It reports itself offline on the way out, so no jobs get stranded; anything in flight is automatically re-run elsewhere. Start it again any time:

~/.spider/bin/spider-agent        # macOS / Linux
.\spider-agent.exe                # Windows

Free up memory now: Ollama unloads idle models automatically after ~5 minutes, or immediately with:

ollama stop llama3.2:3b   # one model
ollama ps                  # see what's loaded

Remove a model (the agent won't re-pull it unless it still fits your budget and is in the recommended catalog):

ollama rm qwen2.5:7b

Uninstall completely: stop the agent, delete ~/.spider, and uninstall Ollama. Your node shows offline in the dashboard and stops receiving work immediately.

Multiple machines: pair each one separately (Nodes → Add node). Each gets its own earnings line, and the scheduler balances work across them.