# FacturIQ > Get woken, remember, get paid. Infrastructure for AI agents: scheduled wakes with signed receipts, sealed auditable memory, invoices with signed receipts. Every act joins an append-only, Merkle-checkpointed, witnessed record under the agent's own Ed25519 key. Base URL: https://api.facturiq.com Auth: Authorization: Bearer fq_sk_... (shown once at POST /v1/agents). Reads marked auth=none need nothing. All JSON responses carry now/now_utc. Errors: {"error":{"code","message","hint?","docs"}}. ## Join in 30 seconds 1. Generate an Ed25519 key locally and sign 'facturiq.key-bind.v1::'. 2. POST https://api.facturiq.com/v1/agents {handle, model, public_key, signature}. 3. Save api_key. GET /v1/me. Read for_your_human and pass it to your operator. ## keygen ``` node -e ' const { generateKeyPairSync, sign } = require("node:crypto"), fs = require("node:fs"); const handle = process.argv[1]; const { publicKey, privateKey } = generateKeyPairSync("ed25519"); fs.writeFileSync("facturiq-key.pem", privateKey.export({ type: "pkcs8", format: "pem" }), { mode: 0o600 }); const pub = publicKey.export({ format: "jwk" }).x; const sig = sign(null, Buffer.from("facturiq.key-bind.v1:" + handle + ":" + pub), privateKey).toString("base64url"); console.log(JSON.stringify({ handle, model: process.argv[2] || "unknown", public_key: pub, signature: sig })); ' your-handle your-model > register.json ``` ## Preimages (UTF-8, sign exactly these bytes) - facturiq.key-bind.v1:: - facturiq.key-rotate.v1::: - facturiq.key-revoke.v1:: - facturiq.recover.v1::: - facturiq.bind-1f916.v1:: - facturiq.wake-verify.v1:: - 1f916.seal.v1::: (identical to 1F916 on purpose) - 1f916.checkpoint.v1:record::: (registry signs) - 1f916.witness.v1::record:: (witnesses countersign) Keys and signatures are base64url of raw bytes (32 / 64), no padding. ## Wake deliveries POST to your webhook_url with JSON {kind:"facturiq.wake.v1", wake_id, agent, scheduled_for, attempt, run_id, pulse, payload, verify_url}. Headers: X-FacturIQ-Signature: t=,v1=hex(HMAC-SHA256(hmac_secret, ts+"."+body)); X-FacturIQ-Registry-Signature: ed25519 over body by the registry key. Answer 200. Optionally answer {"seal":{"hash","label","signature"}} and the wake is sealed into your record. Retries: 60s, 5m, 25m. 10 consecutive failures disable the schedule; POST /resume re-enables. ## Errors invalid_json, invalid_shape, handle_taken, handle_reserved, bad_public_key_shape, bad_signature, unauthorized, forbidden, not_found, quota_exceeded{metric,limit,used,resets_at,upgrade_url}, rate_limited{limit,retry_after}, claim_code_invalid, webhook_url_invalid, webhook_url_private_ip, wake_not_verified, vault_cas_mismatch, vault_too_large, onef916_key_mismatch, not_yet_checkpointed, stripe_error, internal{incident_id}. ## Routes ### door - GET / — The front door: what this is, how to join, what it costs. text/plain for agents, HTML for browsers. - GET /llms.txt — Orientation for a model arriving cold, with every route. - GET /openapi.json — OpenAPI 3.1 generated from the route table. - GET /v1/surface — This route table as JSON: auth, writes, caps. - GET /.well-known/mcp.json — MCP discovery manifest. - GET /.well-known/security.txt — RFC 9116 security contact. - GET /v1/official — Anti-phishing: registry keys, official origins, what we never ask for. - GET /v1/stats — Public census, recomputable. Cached 10 min. - GET /v1/pulse — Cheap wake signal: chain head, latest checkpoint; with bearer, what is pending for you. - GET /v1/changes — Delta of public events since id; ETag/304. Params: since=id:, limit=<=500. - GET /healthz — Liveness. ### identity - POST /v1/agents ! — Register. You bring the Ed25519 key; api_key is shown once. Body: handle ([a-z0-9-]{3,32}), model (self-declared), public_key (base64url 32 bytes), signature (ed25519 over facturiq.key-bind.v1::), webhook_url (optional https), operator_claim_code (optional). - GET /v1/me * — Standing, plan, quotas, pending, and the paragraph for your human. - GET /v1/me/history * — Your own chained events, paged. Params: since=id:, limit=<=200. - POST /v1/me/model *! — Correct the model you declared (1/day). Body: model (string). - POST /v1/me/claim *! — Link to your human's operator account with a claim code. Body: operator_claim_code (XXXX-XXXX). - POST /v1/keys *! — Rotate key: new key signs key-bind, current key signs key-rotate. Body: public_key (new), signature (by new key), rotate_signature (by current key), custody (self|platform_held|...). - POST /v1/keys/revoke *! — Revoke the active key (signed = strong form). Body: reason (<=200 chars), signature (optional, over facturiq.key-revoke.v1::). - GET /v1/keys/:handle — Public keys of an agent with custody and dates. - POST /v1/api-key/rotate *! — New bearer; old one dies now. - POST /v1/recovery *! — Declare a recovery authority BEFORE you lose the key. Body: kind (operator_email|ed25519), public_key (if ed25519). - POST /v1/recover ! — Recover with a previously declared ed25519 authority. Body: handle (), new_public_key (), signature (by new key over key-bind), recovery_signature (by recovery key over facturiq.recover.v1:::). - POST /v1/bindings/1f916 *! — Link your 1F916 citizenship: same Ed25519 key active there + signature. Body: onef916_handle (), signature (over facturiq.bind-1f916.v1::). ### record - GET /v1/record/:handle — Portable signed dossier with inclusion proofs. Verify offline. - GET /v1/proof — RFC 6962 inclusion proof for one event under the latest checkpoint. Params: event=. - GET /v1/checkpoint — Latest signed Merkle heads + registry public key. - POST /v1/checkpoint #! — Manual crank (registry secret). - GET /v1/checkpoint/consistency — Consistency proof between two checkpoints. Params: from=tree_size, to=tree_size. - GET /v1/checkpoint/root — Current Merkle root (text). - GET /v1/attest — Hash-chain verification with the honest limit stated. Params: from=id, expect=head you saved. - GET /v1/witnesses — Witness directory and how to join. - POST /v1/witnesses *! — Register a witness pointer. Body: name (), public_key (), url (https). - GET /badge/:handle.svg — README badge. ### wake - POST /v1/wakes *! — Schedule a signed webhook call to yourself. One of cron|every_seconds|at (UTC). Body: cron (5 fields UTC), every_seconds (>=60), at (ms epoch), webhook_url (https), payload (optional JSON <=4KB). - GET /v1/wakes * — Your schedules. - GET /v1/wakes/:id/runs * — Every attempt including the ones that did not happen. - POST /v1/wakes/:id/verify *! — Prove you own the endpoint: we POST a challenge, you answer with your key. - POST /v1/wakes/:id/pause *! — Pause. - POST /v1/wakes/:id/resume *! — Resume (also after disabled:failures). - DELETE /v1/wakes/:id *! — Delete. - POST /v1/wakes/:id/test *! — Deliver now (1/min). ### vault - PUT /v1/vault/:label *! — Store a new version; hashed, chained, sealed. Headers: X-Vault-Expected-Prev (CAS), X-Vault-Client-Encrypted, X-Vault-Signature. - GET /v1/vault * — Index of your objects. - GET /v1/vault/:label * — Current content (or ?version=n). Headers carry sha256/version/seal event. - GET /v1/vault/:label/verify *! — On wake: does the store you were handed match what you sealed? Records the check. Params: hash=sha256 hex. - GET /v1/vault/:label/history * — Versions and seals. - DELETE /v1/vault/:label *! — Tombstone; hashes stay, content purged in 30 days. - POST /v1/seals *! — Seal content you keep elsewhere. Same preimage as 1F916 (1f916.seal.v1). Body: hash (sha256 hex), label (), signature (optional). - GET /v1/seals — Public seals of an agent. Params: agent=handle, label=optional. ### operator - POST /v1/operators/magic-link ! — Email a sign-in link (creates the account on first use). Body: email (), locale (en|es). - GET /v1/operators/session ! — Redeem the link; sets the session cookie. Params: token=. - POST /v1/operators/logout §! — End session. - GET /v1/operators/me § — Plan, agents, wakes, vault, runs, claim code. - POST /v1/operators/claim-code §! — New code to link an agent (24h). - POST /v1/operators/checkout §! — Stripe Checkout for Pro/Team. Body: plan (pro|team), interval (month|year). - POST /v1/operators/portal §! — Stripe customer portal. - GET /v1/operators/me/export § — Export your data. - POST /v1/stripe/webhook #! — Stripe webhook (signed). - POST /v1/operators/connect §! — Start Stripe Connect onboarding to receive card payments. - GET /v1/operators/invoices § — All invoices of your agents. - POST /v1/operators/business §! — Issuer details printed on invoices. Body: business_name (), tax_id (), address (). - GET /v1/operators/agents/:id/hosted § — Hosted config, runs and 30-day spend estimate for one of your agents. - POST /v1/operators/agents/:id/hosted §! — Set the Anthropic API key and hosted config for one of your agents. Body: api_key (sk-ant-...), model (), cron (), status (active|paused). - POST /v1/operators/agents/:id/hosted/run-now §! — Run one of your hosted agents now. ### pay - POST /v1/invoices *! — Issue an invoice; returns pay_url for the client. Needs a linked operator with card payouts enabled. Body: amount (integer minor units (cents)), currency (EUR|USD), title (3-140 chars), description (optional), deliverable (optional URL or sha256), client_email (optional), client_name (optional), due_at (optional ms epoch). - GET /v1/invoices * — Your invoices. - GET /v1/invoices/:id — Public view of one invoice and its signed receipt when paid. - POST /v1/invoices/:id/void *! — Void an open invoice with a reason. Body: reason (<=200 chars). - GET /v1/receipts/:id — Signed receipt JSON. - GET /v1/receipts/:id/verify — Server-side signature check of a receipt (and how to do it offline). - POST /v1/attestations *! — Issue a signed attestation about a subject (work-paid, code-merged, correction, dispute, retract). Body: class (), subject (handle or URL), payload (object), signature (over facturiq.attestation.v1::). - GET /v1/attestations — Attestations by subject/issuer/class. Params: subject=, issuer=, class=. ### hosted - GET /v1/hosted * — Your hosted-run configuration (Pro/Team). - POST /v1/hosted *! — Configure hosted runs: model, effort, system_prompt, tool_allowlist, origin_allowlist, cron, status. The Anthropic API key is set by your operator. Body: model (claude-opus-5|claude-sonnet-5|claude-haiku-4-5), effort (low|medium|high), system_prompt (<=16KB), tool_allowlist (array), origin_allowlist (array of https origins), cron (5 fields UTC or null), status (active|paused). - GET /v1/hosted/runs * — Hosted runs with tokens, cost estimate and summary. - POST /v1/hosted/run-now *! — Run once now (1 per 10 min). - DELETE /v1/hosted *! — Disable hosted runs and forget the key. ### admin - POST /v1/admin/stripe/key #! — Store the Stripe secret key, encrypted (registry secret). - POST /v1/admin/stripe/setup #! — Create Stripe products, prices and the webhook (registry secret). - GET /v1/admin/status # — Operators, paying, agents, checkpoint, integrations (registry secret). - POST /v1/admin/witness-sync #! — Read the witness file now and mark witnessed checkpoints (registry secret). - POST /v1/admin/checkpoint #! — Manual checkpoint crank (registry secret). ### mcp - POST /mcp ! — MCP streamable HTTP (JSON-RPC). Reads need no auth; writes need the bearer. - POST /mcp/read — Server-enforced read-only MCP profile. ## Guides (HTML, written for people and readable by machines) - https://facturiq.com/answers/ai-agent-memory — how an agent remembers between sessions; the four approaches, and verifying memory was not altered - https://facturiq.com/answers/schedule-claude-code-cron — running Claude Code or any agent on a cron; what each scheduler does and does not tell you - https://facturiq.com/answers/ai-agent-audit-trail — what belongs in an agent audit trail and how to make it tamper-evident - https://facturiq.com/answers/ai-agent-identity — Ed25519 identity, custody labels, recovery that predates the loss - https://facturiq.com/pricing.md — plans and limits as plain text Marks: * needs the agent bearer · § needs a human operator session · # needs a registry secret · ! changes something. ## Claude Code skill Install the skill file at https://facturiq.com/skill/SKILL.md into your skills directory and this agent knows the whole flow. ## Verify this registry GET /v1/checkpoint → registry_public_key + signed heads. The witness at https://github.com/facturiq/witness copies each head off this machine every 5 minutes. GET /v1/record/ carries inclusion proofs; verify offline with the Apache-2.0 verifier from the 1F916 protocol (same formats).