Factory402 API Docs

How to authenticate, pay, and call Factory402 endpoints programmatically.

Base URL

All endpoints are relative to this base URL. HTTPS is required.

Authentication — API Keys (Recommended)

Factory402 uses API key + credit balance authentication. Buy credit packs via Stripe, then pass your key with each request.

Request Flow

1. Create an API key: POST /api/keys
2. Buy a credit pack: POST /api/checkout (redirects to Stripe)
3. Make requests with Authorization: Bearer f402_live_...
4. Credits are deducted per request. Check balance: GET /api/credits

Required Header

• Authorization: Bearer f402_live_<your_key>

Rate Limits

• Free (demo): 5 requests/min, 20/day
• Starter/Growth: 30 requests/min, 500/day
• Scale: 60 requests/min, 2,000/day
• Enterprise: 120 requests/min, 10,000/day

Quickstart — API Key Auth

cURL

# 1. Create an API key
curl -X POST https://api.factory402.com/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Your Name"}'

# Response: {"id":1,"key":"f402_live_abc123...","credits":0,...}

# 2. Buy credits (opens Stripe Checkout)
curl -X POST https://api.factory402.com/api/checkout \
  -H "Content-Type: application/json" \
  -d '{"pack":"growth","email":"[email protected]","api_key":"f402_live_abc123..."}'

# 3. Call a paid endpoint
curl "https://api.factory402.com/api/osint/risk-score?query=Acme+Corp" \
  -H "Authorization: Bearer f402_live_abc123..."

# 4. Check your balance
curl https://api.factory402.com/api/credits \
  -H "Authorization: Bearer f402_live_abc123..."

# 5. View usage history
curl https://api.factory402.com/api/usage \
  -H "Authorization: Bearer f402_live_abc123..."

Python

import requests

API_KEY = "f402_live_your_key_here"
BASE = "https://api.factory402.com"

# Create a key
resp = requests.post(f"{BASE}/api/keys", json={
    "email": "[email protected]",
    "name": "Your Name",
})
key = resp.json()["key"]

# Call an endpoint
resp = requests.get(
    f"{BASE}/api/osint/risk-score",
    params={"query": "Acme Corp"},
    headers={"Authorization": f"Bearer {key}"},
)
data = resp.json()
print(f"Risk score: {data['data']}")
print(f"Credits remaining: {data.get('credits_remaining')}")

JavaScript

const API_KEY = "f402_live_your_key_here";
const BASE = "https://api.factory402.com";

// Call an endpoint
const resp = await fetch(
  `${BASE}/api/osint/risk-score?query=Acme+Corp`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await resp.json();
console.log("Risk score:", data.data);
console.log("Credits remaining:", data.credits_remaining);

Authentication — x402 Protocol (Advanced)

For crypto-native integrations, Factory402 also supports the x402 protocol for machine-to-machine payment authentication. Each paid request carries its own cryptographic payment proof.

Request Flow

1. Send a request to any paid endpoint without payment headers.
2. Receive a 402 Payment Required response containing the price, a unique nonce, and an expiry timestamp.
3. Construct a payment payload, sign it with your private key, and resend the request with three x402 headers.
4. If valid, receive a 200 OK response with the intelligence data.

Required Headers

• x402-payload — Base64-encoded JSON: {"asset":"USD","amount":8,"operator":"factory-payment-operator-v1","nonce":"<unique>","expires":"<timestamp>","endpoint_id":"osint.risk_score.v1"}
• x402-signature — Base64-encoded cryptographic signature of the payload.
• x402-public-key — Base64-encoded public key for signature verification.

Replay Protection

Each nonce can only be used once. Reuse returns 402 with reason "Nonce already used (replay)". Nonces expire after 5 minutes.

Response Envelope

{
  "status": 200,
  "endpoint_id": "osint.risk_score.v1",
  "request_id": "uuid",
  "data": { ... },
  "meta": { "processing_ms": "142", "room": null, "version": "v1" },
  "credits_remaining": 82
}

credits_remaining is included when authenticating via API key.

Error Responses

// 401 — Invalid or missing API key
{"error": "Invalid or inactive API key"}

// 402 — Insufficient credits
{"error": "Insufficient credits", "credits": 3, "required": 10,
 "message": "This endpoint costs 10 credits. You have 3.",
 "purchase_url": "https://factory402.com/endpoints.html#packs"}

// 429 — Rate limit exceeded
{"error": "Rate limit exceeded", "reason": "minute_limit", "retry_after": 23}