Developer Documentation

Everything you need to integrate Captxa — from the three-line HTML snippet to raw API contracts, Ed25519 token verification, and language examples.

Quick Start

Three steps to a fully working integration. Total HTML change: one <script> tag and one empty <div>.

<!-- Add before </body> — ~3 KB, zero external dependencies -->
<script src="https://cdn.jsdelivr.net/gh/HelloCaptxa/PublicJS@latest/script.js"></script>

<!-- Widget mount-point — place it inside your <form> -->
<div id="captcha-widget"></div>

Captxa.render('captcha-widget', {
  serverUrl:      'https://api.captxa.com',
  form:           '#my-form',       // CSS selector — # required
  tokenFieldName: 'captchatoken',   // name attr of the injected hidden <input>
  onVerify: () => {
    // PoW (or puzzle) passed — safe to enable your submit button
    document.getElementById('submit-btn').disabled = false;
  },
  onError: () => {
    // Verification error — ask the user to refresh
    console.error('Captxa verification failed');
  }
});

// On submit, the token is already in the hidden field — just read it
document.getElementById('my-form').addEventListener('submit', async e => {
  e.preventDefault();
  const token = e.target.querySelector('input[name="captchatoken"]')?.value;
  await fetch('/api/my-action', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ captchatoken: token /* + other fields */ })
  });
});

const res  = await fetch('https://api.captxa.com/api/validate', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    captcha_token: req.body.captchatoken,
    secret_key:    process.env.CAPTXA_SECRET_KEY
  })
});
const data = await res.json();

if (!data.Is_Correct) {
  return reply.status(403).json({ error: 'Verification failed' });
}
// data.requests tells you how many times this token has been used

Widget API — Captxa.render()

The widget is a push model: call render() once and it handles everything — PoW in a Web Worker, puzzle UI if triggered, and automatic token injection into your form.

Server-to-server only. Verify a pass token your frontend received and count its usages. Never expose your secret_key to the browser.

{
  "captcha_token": "<Ed25519 pass token>",
  "secret_key":    "<your secret key>"
}

{ "Is_Correct":true, "RequestLimit":false, "requests":1 }

{ "Is_Correct":false, "reason":"invalid_token" }

{ "Is_Correct":true, "RequestLimit":true, "requests":12 }

Ed25519 Public Key

Every pass token issued by the server is signed with an Ed25519 keypair. The public key is published at a stable URL so you can verify tokens locally — without a round-trip to /api/validate. This is useful for high-throughput backends or edge deployments.

Self-verification (skip the API call)

If you need maximum throughput or zero external dependencies at validation time, verify the Ed25519 signature locally. Fetch the public key once at startup and cache it in memory.

import { createPublicKey, verify } from 'node:crypto';

// Fetch once at startup and cache — key is stable between deploys
const PUB_KEY_URL = 'https://api.captxa.com/keys/Ed25519.txt';
let pubKey;

async function loadPublicKey() {
  const b64 = await (await fetch(PUB_KEY_URL)).text();
  const raw = Buffer.from(b64.trim(), 'base64');         // 32 bytes
  pubKey = createPublicKey({ key: raw, format: 'der', type: 'spki' });
  // Or construct the DER envelope manually for raw Ed25519 bytes:
  // const der = Buffer.concat([Buffer.from('302a300506032b6570032100','hex'), raw]);
  // pubKey = createPublicKey({ key: der, format: 'der', type: 'spki' });
}

function verifyCaptchaToken(tokenB64url) {
  const raw = Buffer.from(tokenB64url, 'base64url');
  const sig     = raw.subarray(0, 64);         // first 64 bytes
  const payload = raw.subarray(64);            // remainder
  return verify(null, payload, pubKey, sig);
}

import base64, urllib.request
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature

PUB_KEY_URL = "https://api.captxa.com/keys/Ed25519.txt"

# Load once at startup
def load_public_key():
    raw_b64 = urllib.request.urlopen(PUB_KEY_URL).read().strip()
    raw     = base64.b64decode(raw_b64)          # 32 bytes
    return Ed25519PublicKey.from_public_bytes(raw)

pub_key = load_public_key()

def verify_captcha_token(token_b64url: str) -> bool:
    raw     = base64.urlsafe_b64decode(token_b64url + "==")
    sig     = raw[:64]
    payload = raw[64:]
    try:
        pub_key.verify(sig, payload)
        return True
    except InvalidSignature:
        return False

<?php
// Load once (cache in APCu / Redis for production)
function captxa_load_pubkey(): string {
    $b64 = file_get_contents('https://api.captxa.com/keys/Ed25519.txt');
    return base64_decode(trim($b64));   // 32 bytes
}

function captxa_verify(string $token_b64url, string $pubkey_raw): bool {
    $raw     = sodium_base642bin($token_b64url, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING);
    $sig     = substr($raw, 0, 64);
    $payload = substr($raw, 64);
    return sodium_crypto_sign_verify_detached($sig, $payload, $pubkey_raw);
}

// Usage
$pub   = captxa_load_pubkey();
$valid = captxa_verify($_POST['captchatoken'], $pub);
if (!$valid) { http_response_code(403); exit; }

Full API Reference

The endpoints below are used internally by the JS widget. You typically do not call them directly — they are documented here for transparency and for developers building custom integrations.

{
  "webglrenderer":          "NVIDIA RTX 4090/PCIe",
  "timezone":               "Europe/Barcelona",
  "hardwareconcurrency":    16,
  "innerw": 1920,  "innerh": 1080,
  "availw": 1920,  "availh": 1040,
  "devicememory":           8,
  "webdriver":              false,
  "ischromeruntimemissing": false,
  "errorstacktripwire":     false
}

{
  "challenge_token": "<base64url>",
  "pow_challenge":   "a3f81c...<32 hex chars>",
  "pow_difficulty":  18
}

// 403 escalation signal:
{ "valid":false, "error":"Do_complex_captcha" }

{
  "challenge_token": "<token from /challenge/simp>",
  "pow_solution":    3471829,
  "trajectory": [
    [120, 340, 0],
    [124, 341, 16],
    // ... [x, y, timestamp_ms]
  ]
}

// Response header (pass token):
x-captcha-token: <Ed25519 signed token>

// Response body:
{
  "valid":  true,
  "score":  0.08,
  "mobile": false
}

{
  "challenge_token": "<base64url — contains COMP|ip|ja4|ts|pow|sol_x|sol_y>",
  "pow_challenge":   "b7e3a2...<32 hex chars>",
  "pow_difficulty":  19,
  "puzzle": {
    "background":   "<base64 JPEG — full puzzle image>",
    "piece":        "<base64 PNG — draggable piece with alpha>",
    "piece_start_x": 0,
    "width":         300,
    "height":        150,
    "piece_size":    50
  }
}

{
  "challenge_token": "<token from /challenge/complex>",
  "pow_solution":    7294013,
  "puzzle_x":        187,   // pixels from left
  "puzzle_y":        62,    // pixels from top
  "trajectory": [
    [0, 62, 0], [45, 63, 33],
    // ... [x, y, timestamp_ms]
  ]
}

// Response header:
x-captcha-token: <Ed25519 signed token>

// Response body:
{
  "valid":  true,
  "score":  0.21,
  "mobile": false
}

Error Codes

All error responses share the shape {"valid": false, "error": "<code>"} and are returned with HTTP 403. Codes are fixed strings — safe to match programmatically.

Validate — More Language Examples

All examples call POST /api/validate with a JSON body. Swap in your framework's HTTP client.

async function validateCaptcha(token) {
  const res  = await fetch('https://api.captxa.com/api/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      captcha_token: token,
      secret_key:    process.env.CAPTXA_SECRET_KEY
    })
  });
  if (res.status === 429) return false;   // over request limit
  const data = await res.json();
  return data.Is_Correct === true;
}

import httpx, os

def validate_captcha(token: str) -> bool:
    r = httpx.post(
        "https://api.captxa.com/api/validate",
        json={
            "captcha_token": token,
            "secret_key":    os.environ["CAPTXA_SECRET_KEY"]
        },
        timeout=5.0
    )
    if r.status_code == 429: return False
    return r.json().get("Is_Correct") is True

function validate_captcha(string $token): bool {
    $ch = curl_init('https://api.captxa.com/api/validate');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode([
            'captcha_token' => $token,
            'secret_key'    => getenv('CAPTXA_SECRET_KEY')
        ]),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 5,
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($code === 429) return false;
    return (json_decode($body)->Is_Correct ?? false) === true;
}

func ValidateCaptcha(token string) (bool, error) {
    payload, _ := json.Marshal(map[string]string{
        "captcha_token": token,
        "secret_key":    os.Getenv("CAPTXA_SECRET_KEY"),
    })
    resp, err := http.Post(
        "https://api.captxa.com/api/validate",
        "application/json",
        bytes.NewReader(payload),
    )
    if err != nil { return false, err }
    defer resp.Body.Close()
    if resp.StatusCode == 429 { return false, nil }
    var result struct{ IsCorrect bool `json:"Is_Correct"` }
    json.NewDecoder(resp.Body).Decode(&result)
    return result.IsCorrect, nil
}

Rate Limits & Limits

All limits apply per registered domain. The CAPTCHA endpoints are protected by a Count-Min Sketch keyed on ip | ja4 | ja4o | domain — exceeding it silently escalates to the complex path rather than hard-blocking.