01 · getting started

The NoneCap hCaptcha API.

A RESTful, JSON-over-HTTPS API for solving hCaptcha programmatically. Send a sitekey and the page URL; we return a real P1_ token your client submits as h-captcha-response: the same shape hCaptcha hands back after a human solves the challenge.

Base URL

api.nonecap.com/v1

Auth scheme

Bearer token

Content type

application/json

Captcha

hCaptcha

Image-recognition solvers produce low-trust tokens that hCaptcha enterprise flags within seconds. NoneCap returns a finished token that passes hCaptcha's server-side checks, so it actually authorises the request it was issued for.

All endpoints live under https://api.nonecap.com. HTTPS only. JSON in, JSON out. Authentication on every request.

Quickstart

Sign in to the dashboard and mint an API key (nc_live_…).
POST a solve to /v1/solves. Add ?wait=N (1-90 s) to block until the solve completes.
Inject the returned P1_ token into the target form's h-captcha-response field and submit.

cURL

curl https://api.nonecap.com/v1/solves?wait=30 \
  -H "Authorization: Bearer nc_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "type":    "hcaptcha",
    "sitekey": "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
    "url":     "https://target.example/login"
  }'

Node

const res = await fetch("https://api.nonecap.com/v1/solves?wait=30", {
  method:  "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NONECAP_KEY}`,
    "Content-Type":  "application/json",
  },
  body: JSON.stringify({
    type:    "hcaptcha",
    sitekey: "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
    url:     "https://target.example/login",
  }),
});

const solve = await res.json();
console.log(solve.token);

Python

import os, requests

res = requests.post(
    "https://api.nonecap.com/v1/solves",
    params={"wait": 30},
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
    json={
        "type":    "hcaptcha",
        "sitekey": "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
        "url":     "https://target.example/login",
    },
)

solve = res.json()
print(solve["token"])

body, _ := json.Marshal(map[string]string{
    "type":    "hcaptcha",
    "sitekey": "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
    "url":     "https://target.example/login",
})

req, _ := http.NewRequest("POST",
    "https://api.nonecap.com/v1/solves?wait=30", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
req.Header.Set("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

var solve struct{ Token string `json:"token"` }
json.NewDecoder(res.Body).Decode(&solve)
fmt.Println(solve.Token)

Authentication

API keys are minted from the dashboard. Format: nc_live_ + 32 base64url characters. Send on every request:

Authorization: Bearer nc_live_a8f2K9...

Errors

401 unauthorized: missing, malformed, revoked, or unknown key.
402 insufficient_credits: valid key but balance < 1; only raised on calls that consume credits.

Sign up in the dashboard to mint a key and claim 100 free credits. A future nc_test_ prefix is reserved for test-mode keys.

cURL

curl https://api.nonecap.com/v1/me \
  -H "Authorization: Bearer nc_live_••••"

Node

const res = await fetch("https://api.nonecap.com/v1/me", {
  headers: { "Authorization": `Bearer ${process.env.NONECAP_KEY}` },
});
console.log(await res.json());

Python

import os, requests
res = requests.get(
    "https://api.nonecap.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
)
print(res.json())

req, _ := http.NewRequest("GET", "https://api.nonecap.com/v1/me", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
io.Copy(os.Stdout, res.Body)

Errors

Every non-2xx response follows the same envelope:

{
  "error": {
    "code":    "insufficient_credits",
    "message": "Your account has 0 credits remaining. Top up at https://dashboard.nonecap.com/billing.",
    "param":   null
  }
}

param names the offending request field for validation errors; otherwise null.

HTTP status codes

400

BAD REQUEST

invalid_request: Malformed JSON or missing required structural field.

401

UNAUTHORIZED

unauthorized: Missing, malformed, revoked, or unknown API key.

402

PAYMENT REQUIRED

insufficient_credits: Not enough credits to start the solve.

403

FORBIDDEN

account_locked: The owning account has been locked by an administrator.

404

NOT FOUND

not_found: Solve id unknown or purged after retention.

409

CONFLICT

conflict: Cancel on already-terminal solve.

422

UNPROCESSABLE

validation_error: Bad field value (unknown type, bad url, etc.).

429

RATE LIMITED

rate_limited: Too many requests; slow down.

429

RATE LIMITED

concurrency_limit_exceeded: Too many solves in flight for this account (default 5; contact support to raise). Retry once one completes.

500

SERVER ERROR

internal_error: Unexpected server error.

503

UNAVAILABLE

pool_exhausted: All workers busy; Retry-After header set.

Solve-failure codes

These ride in Solve.error.code on a terminal, non-solved solve. status is failed, cancelled, or expired. The request succeeded; the solve didn't produce a token.

challenge_not_loaded

The hCaptcha challenge never displayed. Usually proxy/IP reputation — retry with a different proxy.

token_not_granted

The challenge was completed but hCaptcha did not issue a token. Retry; if it persists, use a higher-quality proxy IP.

challenge_expired

hCaptcha expired the challenge before the solve completed. Retry the solve.

challenge_errored

hCaptcha aborted the challenge widget. Retry the solve.

proxy_error

The supplied proxy failed to connect or auth, or its IP was refused by hCaptcha. Fix or swap the proxy.

target_unreachable

The target url did not load. Verify it is reachable.

vision_error

Internal error in the solving pipeline. Retry; contact support if it persists.

cancelled

The caller cancelled the job.

expired

Solve exceeded its time budget before producing a token (never billed).

402 insufficient_credits

{
  "error": {
    "code":    "insufficient_credits",
    "message": "Your account has 0 credits remaining. Top up at https://dashboard.nonecap.com/billing.",
    "param":   null
  }
}

200: solve.status = failed

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "failed",
  "error":           {
    "code":    "challenge_not_loaded",
    "message": "The hCaptcha challenge never displayed. This usually means the proxy IP has poor reputation with hCaptcha — retry with a different proxy."
  },
  "credits_charged": 0,
  "finished_at":     "2026-05-20T11:42:06Z"
}

Versioning

This is v1. Breaking changes will ship under v2 with at least 12 months of v1 support.

Resource shapes are additive within a major version: new optional fields can appear at any time. Clients should ignore unknown fields rather than treating them as an error.

Pagination

List endpoints use cursor-based pagination. The cursor is the id of the last item you received; pass it as starting_after on the next request.

limit: 1-100, default 20.
starting_after: a solve_… id (exclusive cursor).
Responses carry has_more: boolean. There is no separate cursor field: read the last item's id.

cURL

curl "https://api.nonecap.com/v1/solves?limit=20&starting_after=solve_01HQF7K3JKWZX" \
  -H "Authorization: Bearer nc_live_••••"

Node

async function* listAll() {
  let cursor: string | undefined;
  while (true) {
    const url = new URL("https://api.nonecap.com/v1/solves");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("starting_after", cursor);
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.NONECAP_KEY}` },
    });
    const page = await res.json();
    for (const item of page.data) yield item;
    if (!page.has_more) return;
    cursor = page.data[page.data.length - 1].id;
  }
}

Python

import os, requests

def list_all():
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor: params["starting_after"] = cursor
        page = requests.get(
            "https://api.nonecap.com/v1/solves",
            params=params,
            headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
        ).json()
        for item in page["data"]:
            yield item
        if not page["has_more"]:
            return
        cursor = page["data"][-1]["id"]

func listAll() ([]Solve, error) {
    var all []Solve
    var cursor string
    for {
        u, _ := url.Parse("https://api.nonecap.com/v1/solves")
        q := u.Query()
        q.Set("limit", "100")
        if cursor != "" { q.Set("starting_after", cursor) }
        u.RawQuery = q.Encode()
        req, _ := http.NewRequest("GET", u.String(), nil)
        req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
        res, err := http.DefaultClient.Do(req)
        if err != nil { return nil, err }
        defer res.Body.Close()
        var page struct {
            Data    []Solve `json:"data"`
            HasMore bool    `json:"has_more"`
        }
        json.NewDecoder(res.Body).Decode(&page)
        all = append(all, page.Data...)
        if !page.HasMore { return all, nil }
        cursor = page.Data[len(page.Data)-1].ID
    }
}

02 · solves

The solve object

A solve represents one captcha-solving job: its parameters, the worker that picked it up, the resulting token, and how much it cost you.

Attributes

id string optional

Prefixed ULID, e.g. solve_01HQF7K3JKWZX.

object "solve" optional

Constant.

type string · enum optional

Captcha type. See Captcha types below.

hcaptchahcaptcha_enterprise

status string · enum optional

Current state. Terminal states are solved, failed, cancelled and expired.

pendingsolvingsolvedfailedcancelledexpired

sitekey string optional

Echoed from the original request.

url string optional

Echoed from the original request.

token string · nullable optional

Present iff status = solved.

error object · nullable optional

Present on failed, cancelled, and expired; null otherwise. See Errors.

credits_charged integer · nullable optional

Final billed amount. null until terminal.

created_at string · RFC 3339 optional

When the job was accepted.

started_at string · nullable optional

When a worker picked it up.

finished_at string · nullable optional

When the solve reached a terminal state.

queue_ms integer · nullable optional

Milliseconds spent waiting in the queue before a worker picked the solve up (started_at − created_at). For a solve that went terminal without ever being picked up — e.g. expired or cancelled while still queued — this is the full wait (finished_at − created_at). null while still pending.

resolve_ms integer · nullable optional

Milliseconds of actual solving (finished_at − started_at). null if the solve never left the queue, or hasn't finished yet. Pair with queue_ms to tell capacity (queue) from solver performance (resolve).

Lifecycle

pending → solving → solved
                  → failed
                  → expired     (exceeded time budget / reclaimed)

pending | solving → cancelled   (via DELETE)

Records are purged after a 30-day retention window; after that GET /v1/solves/{id} returns 404. That retention is separate from the expired status above.

Captcha types

hcaptcha captcha type optional

Required: sitekey, url. Optional: user_agent, proxy. Returns a P1_ token.

hcaptcha_enterprise captcha type optional

Required: sitekey, url, rqdata. Optional: user_agent, proxy. Returns a P1_ token.

recaptcha_v2 reserved optional

Reserved for future expansion.

recaptcha_v3 reserved optional

Reserved for future expansion.

cloudflare_turnstile reserved optional

Reserved for future expansion.

funcaptcha reserved optional

Reserved for future expansion.

Solve example

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "solved",
  "sitekey":         "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
  "url":             "https://target.example/login",
  "token":           "P1_eyJ0eXAi...UV8w",
  "error":           null,
  "credits_charged": 1,
  "created_at":      "2026-05-20T11:42:01Z",
  "started_at":      "2026-05-20T11:42:02Z",
  "finished_at":     "2026-05-20T11:42:06Z",
  "queue_ms":        1000,
  "resolve_ms":      4000
}

Create a solve

POST https://api.nonecap.com /v1/solves

Submit a new captcha solve. Credit is debited at submit time and refunded automatically on failed, cancelled, or expired.

Body parameters

type string required

Captcha type to solve.

hcaptchahcaptcha_enterprise

sitekey string required

The sitekey hCaptcha gave you.

url string required

Page URL where the challenge appears.

rqdata string optional

Required for hcaptcha_enterprise; carries the IP-bound challenge data.

user_agent string optional

Match the user agent your real client uses.

proxy string | object optional

URL string (http://user:pass@host:port) or object form with host, port, scheme, username, password.

webhook_url string optional

Receive a solve.completed callback when the solve reaches a terminal state.

Query parameters

wait integer optional

Block up to N seconds (1-90); return as soon as the solve reaches a terminal state.

Responses

202

ACCEPTED

pending: Async: solve is still in flight.

200

terminal: Set ?wait and the solve reached a terminal state in time.

422

UNPROCESSABLE

validation_error: Malformed body or invalid field value.

402

PAYMENT REQUIRED

insufficient_credits: Balance < 1 credit.

429

TOO MANY

concurrency_limit_exceeded: Account already at its concurrency cap (default 5). Retry once one completes.

503

UNAVAILABLE

pool_exhausted: All workers busy. See Retry-After header.

POST /v1/solves

cURL

curl https://api.nonecap.com/v1/solves?wait=30 \
  -H "Authorization: Bearer nc_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "type":    "hcaptcha",
    "sitekey": "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
    "url":     "https://target.example/login",
    "proxy":   "http://user:[email protected]:8080"
  }'

Node

const res = await fetch("https://api.nonecap.com/v1/solves?wait=30", {
  method:  "POST",
  headers: {
    Authorization:  `Bearer ${process.env.NONECAP_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type:    "hcaptcha",
    sitekey: "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
    url:     "https://target.example/login",
  }),
});
const solve = await res.json();

Python

import os, requests
solve = requests.post(
    "https://api.nonecap.com/v1/solves",
    params={"wait": 30},
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
    json={
        "type":    "hcaptcha",
        "sitekey": "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
        "url":     "https://target.example/login",
    },
).json()

body, _ := json.Marshal(map[string]string{
    "type":    "hcaptcha",
    "sitekey": "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
    "url":     "https://target.example/login",
})
req, _ := http.NewRequest("POST",
    "https://api.nonecap.com/v1/solves?wait=30", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

202 pending

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "pending",
  "sitekey":         "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
  "url":             "https://target.example/login",
  "token":           null,
  "error":           null,
  "credits_charged": null,
  "created_at":      "2026-05-20T11:42:02Z",
  "started_at":      null,
  "finished_at":     null,
  "queue_ms":        null,
  "resolve_ms":      null
}

200 solved

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "solved",
  "sitekey":         "f5ab1c2d-7e8f-4a9b-b1c2-d3e4f5a6b7c8",
  "url":             "https://target.example/login",
  "token":           "P1_eyJ0eXAi...UV8w",
  "error":           null,
  "credits_charged": 1,
  "created_at":      "2026-05-20T11:42:01Z",
  "started_at":      "2026-05-20T11:42:02Z",
  "finished_at":     "2026-05-20T11:42:06Z",
  "queue_ms":        1000,
  "resolve_ms":      4000
}

Retrieve a solve

GET https://api.nonecap.com /v1/solves/{id}

Fetch the current state of a solve by id. With ?wait=N (1-90 s), the call blocks until the solve reaches a terminal state or the wait expires.

Path parameters

id string required

Prefixed ULID of the solve, e.g. solve_01HQF7K3JKWZX.

Query parameters

wait integer optional

Block up to N seconds (1-90); return as soon as the solve reaches a terminal state.

Responses

200

Terminal (solved/failed/cancelled/expired). Returns the full solve object.

202

ACCEPTED

Still pending/solving. Poll again (or use ?wait).

404

NOT FOUND

Solve id unknown or purged after the 30-day retention window.

GET /v1/solves/{id}

cURL

curl https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX?wait=10 \
  -H "Authorization: Bearer nc_live_••••"

Node

const res = await fetch(
  "https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX?wait=10",
  { headers: { Authorization: `Bearer ${process.env.NONECAP_KEY}` } },
);
const solve = await res.json();

Python

import os, requests
solve = requests.get(
    "https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX",
    params={"wait": 10},
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
).json()

req, _ := http.NewRequest("GET",
    "https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX?wait=10", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

200 solved

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "solved",
  "token":           "P1_eyJ0eXAi...UV8w",
  "credits_charged": 1,
  "created_at":      "2026-05-20T11:42:01Z",
  "started_at":      "2026-05-20T11:42:02Z",
  "finished_at":     "2026-05-20T11:42:06Z",
  "queue_ms":        1000,
  "resolve_ms":      4000
}

202 pending

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "solving",
  "token":           null,
  "credits_charged": null,
  "created_at":      "2026-05-20T11:42:01Z",
  "started_at":      "2026-05-20T11:42:02Z",
  "finished_at":     null,
  "queue_ms":        1000,
  "resolve_ms":      null
}

List solves

GET https://api.nonecap.com /v1/solves

Cursor-paginated history of solves for the authenticated account. Newest first.

Query parameters

limit integer optional

Number of solves to return. Default 20, range 1-100.

starting_after string optional

Pagination cursor: id of the last solve from the previous page.

status string optional

Filter by solve status.

pendingsolvingsolvedfailedcancelledexpired

type string optional

Filter by captcha type.

hcaptchahcaptcha_enterprise

Response carries has_more: boolean. There is no separate cursor field. The cursor is the id of the last item in data.

GET /v1/solves

cURL

curl "https://api.nonecap.com/v1/solves?limit=20&status=solved" \
  -H "Authorization: Bearer nc_live_••••"

Node

const url = new URL("https://api.nonecap.com/v1/solves");
url.searchParams.set("limit", "20");
url.searchParams.set("status", "solved");
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.NONECAP_KEY}` },
});
const page = await res.json();
for (const solve of page.data) console.log(solve.id);

Python

import os, requests
page = requests.get(
    "https://api.nonecap.com/v1/solves",
    params={"limit": 20, "status": "solved"},
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
).json()
for s in page["data"]:
    print(s["id"])

u, _ := url.Parse("https://api.nonecap.com/v1/solves")
q := u.Query()
q.Set("limit", "20"); q.Set("status", "solved")
u.RawQuery = q.Encode()
req, _ := http.NewRequest("GET", u.String(), nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

200 list

{
  "object": "list",
  "data": [
    { "id": "solve_01HQF7K3JKWZX", "type": "hcaptcha", "status": "solved", "credits_charged": 1, "finished_at": "2026-05-20T11:42:06Z" },
    { "id": "solve_01HQF7K3JLNAB", "type": "hcaptcha", "status": "solved", "credits_charged": 1, "finished_at": "2026-05-20T11:43:11Z" },
    { "id": "solve_01HQF7K3JKWZY", "type": "hcaptcha", "status": "solved", "credits_charged": 1, "finished_at": "2026-05-20T11:44:27Z" },
    { "id": "solve_01HQF7K3JKABC", "type": "hcaptcha", "status": "failed", "credits_charged": 0, "finished_at": "2026-05-20T11:45:00Z" }
  ],
  "has_more": true
}

Cancel a solve

DELETE https://api.nonecap.com /v1/solves/{id}

Cancel a pending or solving solve. The credit is refunded automatically.

Path parameters

id string required

Prefixed ULID of the solve to cancel, e.g. solve_01HQF7K3JKWZX.

Responses

200

Cancelled. Returns the solve with status: "cancelled".

409

CONFLICT

conflict: Solve already reached a terminal state and cannot be cancelled.

404

NOT FOUND

not_found: Unknown solve id.

DELETE /v1/solves/{id}

cURL

curl -X DELETE https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX \
  -H "Authorization: Bearer nc_live_••••"

Node

await fetch("https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX", {
  method:  "DELETE",
  headers: { Authorization: `Bearer ${process.env.NONECAP_KEY}` },
});

Python

import os, requests
requests.delete(
    "https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX",
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
)

req, _ := http.NewRequest("DELETE",
    "https://api.nonecap.com/v1/solves/solve_01HQF7K3JKWZX", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
http.DefaultClient.Do(req)

200 cancelled

{
  "id":              "solve_01HQF7K3JKWZX",
  "object":          "solve",
  "type":            "hcaptcha",
  "status":          "cancelled",
  "token":           null,
  "credits_charged": 0,
  "created_at":      "2026-05-20T11:42:02Z",
  "started_at":      "2026-05-20T11:42:02Z",
  "finished_at":     "2026-05-20T11:42:04Z"
}

03 · account

Account & balance

GET https://api.nonecap.com /v1/me

Returns the authenticated account plus the current credit balance. Useful for showing balance in your own dashboard or as a pre-flight before a batch.

Response

object "account" optional

Constant.

id string optional

Prefixed ULID, e.g. user_01HQ….

email string optional

Verified email on the account.

credits_balance integer optional

Available solves remaining.

created_at string · RFC 3339 optional

Account creation timestamp.

GET /v1/me

cURL

curl https://api.nonecap.com/v1/me \
  -H "Authorization: Bearer nc_live_••••"

Node

const res = await fetch("https://api.nonecap.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.NONECAP_KEY}` },
});
const me = await res.json();
console.log(me.credits_balance);

Python

import os, requests
me = requests.get(
    "https://api.nonecap.com/v1/me",
    headers={"Authorization": f"Bearer {os.environ['NONECAP_KEY']}"},
).json()
print(me["credits_balance"])

req, _ := http.NewRequest("GET", "https://api.nonecap.com/v1/me", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("NONECAP_KEY"))
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
var me struct{ CreditsBalance int `json:"credits_balance"` }
json.NewDecoder(res.Body).Decode(&me)
fmt.Println(me.CreditsBalance)

200 account

{
  "object":          "account",
  "id":              "user_01HQF7K3JKWZX",
  "email":           "[email protected]",
  "credits_balance": 4827,
  "created_at":      "2026-04-01T00:00:00Z"
}

04 · webhooks

Webhooks

Rolling out Spec'd, delivery rolling out. You can pass webhook_url on a solve today and it's stored on the record. Outbound delivery starts when the worker ships (phase 3.5). The signature scheme below is final and won't change.

When a solve reaches a terminal state, NoneCap POSTs the event to webhook_url. Use the headers below to verify the request came from us before acting on it.

Headers sent

Content-Type: application/json
User-Agent: NoneCap-Webhook/1
X-NoneCap-Event: solve.completed
X-NoneCap-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>

Signature scheme

The signed payload is "<t>.<raw_body>" (note the literal dot). Verification is HMAC-SHA256 with the webhook secret from your dashboard. Reject any signature where t is older than 5 minutes. This defeats replay.

Delivery & retries

Expect a 2xx within 5 seconds. Non-2xx or timeout triggers a retry.
Retry schedule: +30 s, +5 min, +30 min (3 attempts total).
After the final failure the webhook is dropped. The solve itself is unaffected: fetch it from /v1/solves/{id} as a fallback.

Inbound request

POST /your-webhook HTTP/1.1
Host: your-app.example
Content-Type: application/json
User-Agent: NoneCap-Webhook/1
X-NoneCap-Event: solve.completed
X-NoneCap-Signature: t=1747680126,v1=4f8b...3d2a

{ "id":"evt_01HQF7K3JKWZX", "type":"solve.completed", ... }

Node

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t   = parts.t;
  const sig = parts.v1;
  if (!t || !sig) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;     // 5 min replay window
  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(sig, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = parts.get("t"); sig = parts.get("v1")
    if not (t and sig):                                          return False
    if abs(time.time() - int(t)) > 300:                          return False  # 5-min replay window
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "strings"
    "strconv"
    "time"
)

func Verify(rawBody []byte, header, secret string) bool {
    parts := map[string]string{}
    for _, p := range strings.Split(header, ",") {
        kv := strings.SplitN(p, "=", 2)
        if len(kv) == 2 { parts[kv[0]] = kv[1] }
    }
    t, err := strconv.ParseInt(parts["t"], 10, 64)
    if err != nil { return false }
    if abs64(time.Now().Unix() - t) > 300 { return false }            // 5-min replay window
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(strconv.FormatInt(t, 10) + "."))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))
    sig, _ := hex.DecodeString(parts["v1"])
    exp, _ := hex.DecodeString(expected)
    return hmac.Equal(sig, exp)
}

Event types

NoneCap currently emits one event type:

solve.completed event optional

Fires when a solve reaches any terminal state: solved, failed, cancelled, or expired. data carries the full solve object.

Dispatch on data.status to tell success from failure. A single solve.completed covers all terminal cases.

solve.completed

{
  "id":      "evt_01HQF7K3JKWZX",
  "type":    "solve.completed",
  "created": "2026-05-20T11:42:06Z",
  "data": {
    "object":          "solve",
    "id":              "solve_01HQF7K3JKWZX",
    "status":          "solved",
    "token":           "P1_eyJ0...UV8w",
    "credits_charged": 1
  }
}