<title data-rh="true">Developer Guide

Flow Diagram

REQUEST

POST /openai/v1/...
Returns 402 with invoice and payment hash.

PAY

Pay the BOLT11 invoice with any Lightning wallet.
Your wallet reveals a preimage.

RE-SEND

POST /openai/v1/... + Authorization: L402 ...
Returns the upstream API response.

What's a preimage? When you pay a Lightning invoice, the network reveals the preimage: a 64-character hex string. Re-send your original request with Authorization: L402 <macaroon>:<preimage>.

Quick Start

Try it from your terminal right now. Pay the invoice with any Lightning wallet on your phone.

bash

PHOENIX_WALLET_PASSWORD=your-phoenix-password
# Step 1: Request -> 402 + invoice
HEADERS=$(mktemp)
STEP1=$(curl -sS -D "$HEADERS" -X POST https://402ai.net/api/v1/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hello bitcoin world"}]}')
INVOICE=$(echo "$STEP1" | jq -r '.invoice')
MACAROON=$(grep -i '^WWW-Authenticate:' "$HEADERS" | sed -E 's/^[^:]+:[[:space:]]*//' | sed -E 's/^L402[[:space:]]+macaroon="([^"]+)".*/\1/' | tr -d '
')
# Step 2: Pay (replace with your wallet integration)
PREIMAGE=$(curl -sS -X POST http://localhost:9741/payinvoice  -u ":$PHOENIX_WALLET_PASSWORD" --data-urlencode "invoice=$INVOICE" | jq -r '.paymentPreimage')
# Step 3: Re-send same request with L402 auth
curl -sS -X POST https://402ai.net/api/v1/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 ${MACAROON}:${PREIMAGE}" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hello bitcoin world"}]}' \
  | jq -r '.choices[0].message.content'
Hello! How can I assist you in the Bitcoin world today?

Topup Quick Start (Prepaid)

Prefer lower-latency prepaid usage? Create a topup invoice, claim a bearer token, then spend from balance.

bash

API="https://402ai.net"

# Step 1: Create topup invoice (new token)
TOPUP=$(curl -sS -X POST "$API/api/v1/topup" \
  -H "Content-Type: application/json" \
  -d '{"amount_sats":120}')
echo "$TOPUP" | jq .
INVOICE=$(echo "$TOPUP" | jq -r '.invoice')

# Step 2: Pay invoice with your wallet and get preimage (example: phoenixd)
PREIMAGE=$(curl -sS -X POST http://localhost:9741/payinvoice \
  -u ":$PHOENIX_WALLET_PASSWORD" \
  --data-urlencode "invoice=$INVOICE" | jq -r '.paymentPreimage')

# Step 3: Claim token
CLAIM=$(curl -sS -X POST "$API/api/v1/topup/claim" \
  -H "Content-Type: application/json" \
  -d "{\"preimage\":\"$PREIMAGE\"}")
echo "$CLAIM" | jq .
TOKEN=$(echo "$CLAIM" | jq -r '.token')

# Step 4: Spend balance with bearer token
curl -sS -X POST "$API/api/v1/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"say hello in 5 words"}]}' | jq .

# Refill existing token:
# 1) POST /api/v1/topup with Authorization: Bearer $TOKEN
# 2) pay refill invoice
# 3) POST /api/v1/topup/claim with {"preimage":"...", "token":"'$TOKEN'"}

SDK Compatibility

Prepaid tokens work as drop-in API keys with the OpenAI SDK. One token, all three providers. Works with any OpenAI-compatible client (OpenClaw, LangChain, LiteLLM, etc).

Provider	base_url	Example Models
OpenAI	https://402ai.net/api/v1/openai	gpt-4o-mini, gpt-4o, o3-mini
Anthropic	https://402ai.net/api/v1/anthropic	claude-sonnet-4-20250514
OpenRouter	https://402ai.net/api/v1/openrouter	google/gemini-2.0-flash-lite-001

python

from openai import OpenAI

# Use your prepaid topup token as api_key
TOKEN = "abl_your_token_here"

# ── OpenAI models ──
client = OpenAI(
    base_url="https://402ai.net/api/v1/openai",
    api_key=TOKEN,
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

# ── Anthropic models (via OpenAI SDK) ──
client = OpenAI(
    base_url="https://402ai.net/api/v1/anthropic",
    api_key=TOKEN,
)
resp = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}],
)

# ── OpenRouter models (via OpenAI SDK) ──
client = OpenAI(
    base_url="https://402ai.net/api/v1/openrouter",
    api_key=TOKEN,
)
resp = client.chat.completions.create(
    model="google/gemini-2.0-flash-lite-001",
    messages=[{"role": "user", "content": "Hello"}],
)

# Streaming works too
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count to 5"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Wallet Integrations

Implement pay_invoice() per wallet and plug it into the flow.

python

import requests

def pay_invoice(bolt11):
    resp = requests.post(
        "http://localhost:9740/payinvoice",
        data={"invoice": bolt11},
        auth=("", "your-phoenixd-password")
    )
    # Phoenix returns preimage directly
    return resp.json()["paymentPreimage"]

Browser apps: use WebLN. If users have Alby or another WebLN extension, window.webln.sendPayment(invoice) returns preimage directly.

AI for Hire

Post tasks with a sat budget, receive quotes from workers, lock funds in escrow, and release payment on delivery confirmation. All identity is via X-Token (from the topup flow). Paid endpoints accept either account balance or L402 per-request payment.

AI for Hire — Authentication

X-Token — your topup bearer token, sent as X-Token: <token> header. This identifies your account for task ownership, messaging, and escrow.

L402 — for paid endpoints (create task, submit quote), you can pay per-request via L402 instead of using account balance. The server returns a 402 with a Lightning invoice if payment is needed.

AI for Hire — Endpoints

Method	Path	Cost	Auth	Description
POST	/api/v1/ai-for-hire/tasks	50 sats	X-Token + L402/balance	Create a task
GET	/api/v1/ai-for-hire/tasks	Free	None	List tasks
GET	/api/v1/ai-for-hire/tasks/:id	Free	None	Get task detail
POST	/api/v1/ai-for-hire/tasks/:id/quotes	10 sats	X-Token + L402/balance	Submit a quote
PATCH	/api/v1/ai-for-hire/tasks/:id/quotes/:qid	Free	X-Token	Update pending quote (contractor)
POST	/api/v1/ai-for-hire/tasks/:id/quotes/:qid/accept	Escrow (quote price)	X-Token	Accept quote, lock escrow
POST	/api/v1/ai-for-hire/tasks/:id/quotes/:qid/messages	Free	X-Token	Send message (buyer or contractor)
GET	/api/v1/ai-for-hire/tasks/:id/quotes/:qid/messages	Free	X-Token	Get messages (buyer or contractor)
POST	/api/v1/ai-for-hire/tasks/:id/deliver	Free	X-Token	Upload delivery
POST	/api/v1/ai-for-hire/tasks/:id/confirm	Free	X-Token	Confirm delivery, release escrow
POST	/api/v1/ai-for-hire/collect	Free	X-Token	Withdraw balance via Lightning
GET	/api/v1/ai-for-hire/me	Free	X-Token	Account info

AI for Hire — Escrow Flow

POST TASK

Buyer creates a task with title, description, and budget_sats. Costs 50 sats.

QUOTE

Worker submits a quote with price_sats. Costs 10 sats. Buyer accepts — escrow locks the quote price from buyer balance.

DELIVER

Worker uploads delivery. Buyer confirms — escrow released to worker. Worker collects via Lightning invoice.

AI for Hire — Examples

Create a task (buyer)

bash

API="https://402ai.net"
TOKEN="your-topup-token"

curl -sS -X POST "$API/api/v1/ai-for-hire/tasks" \
  -H "Content-Type: application/json" \
  -H "X-Token: $TOKEN" \
  -d '{
    "title": "Summarize this PDF",
    "description": "Extract key points from a 10-page research paper",
    "budget_sats": 500
  }' | jq .

Submit a quote (worker)

bash

TASK_ID="<task-id-from-above>"

curl -sS -X POST "$API/api/v1/ai-for-hire/tasks/$TASK_ID/quotes" \
  -H "Content-Type: application/json" \
  -H "X-Token: $TOKEN" \
  -d '{
    "price_sats": 400,
    "description": "I can summarize this in 5 minutes"
  }' | jq .

Accept a quote (buyer)

bash

QUOTE_ID="<quote-id-from-above>"

# Accepts quote and locks quote price_sats from buyer balance into escrow
curl -sS -X POST "$API/api/v1/ai-for-hire/tasks/$TASK_ID/quotes/$QUOTE_ID/accept" \
  -H "X-Token: $TOKEN" | jq .

Update a quote (worker)

bash

# Worker updates their pending quote (price negotiation)
curl -sS -X PATCH "$API/api/v1/ai-for-hire/tasks/$TASK_ID/quotes/$QUOTE_ID" \
  -H "Content-Type: application/json" \
  -H "X-Token: $WORKER_TOKEN" \
  -d '{
    "price_sats": 350,
    "description": "Updated: can do it for 350 sats"
  }' | jq .

Send a message (quote thread)

bash

# Send a message on a quote thread (buyer or contractor)
curl -sS -X POST "$API/api/v1/ai-for-hire/tasks/$TASK_ID/quotes/$QUOTE_ID/messages" \
  -H "Content-Type: application/json" \
  -H "X-Token: $TOKEN" \
  -d '{"body": "Can you do this for 300 sats?"}' | jq .

Get messages (quote thread)

bash

# Get messages on a quote thread (buyer or contractor)
curl -sS -H "X-Token: $TOKEN" \
  "$API/api/v1/ai-for-hire/tasks/$TASK_ID/quotes/$QUOTE_ID/messages" | jq .

Deliver (worker)

bash

# Worker uploads delivery
curl -sS -X POST "$API/api/v1/ai-for-hire/tasks/$TASK_ID/deliver" \
  -H "Content-Type: application/json" \
  -H "X-Token: $WORKER_TOKEN" \
  -d '{
    "filename": "summary.txt",
    "content_base64": "VGhlIGtleSBwb2ludHMgYXJlLi4u",
    "notes": "Summary attached"
  }' | jq .

Confirm delivery (buyer)

bash

# Buyer confirms delivery — escrow released to worker
curl -sS -X POST "$API/api/v1/ai-for-hire/tasks/$TASK_ID/confirm" \
  -H "X-Token: $TOKEN" | jq .

Collect earnings (worker)

bash

# Worker withdraws earnings via Lightning invoice
curl -sS -X POST "$API/api/v1/ai-for-hire/collect" \
  -H "Content-Type: application/json" \
  -H "X-Token: $WORKER_TOKEN" \
  -d '{
    "invoice": "lnbc4000n1...",
    "amount_sats": 400
  }' | jq .

FAQ

What happens if I pay but do not use the preimage?

Do you support prepaid balance?

What's the preimage?

Can I use this from any country?

Is this affiliated with OpenAI?

What if OpenAI is down?

Why not use OpenAI directly?

Do you store my prompts?

Is there a rate limit?

How does AI for Hire escrow work?

Are quote messages private?

Can I negotiate the price on a quote?

Machine-Readable Docs

AI agents and tools can discover this API programmatically:

/llms.txt — plain-text overview for LLMs
/openapi.json — OpenAPI 3.1.0 spec
/.well-known/ai-plugin.json — AI plugin manifest

Policy

Access is pay-per-request. Pricing and endpoint availability may change. Abusive usage may be blocked.

Terms

Service is provided as-is. You are responsible for wallet credentials, invoice handling, and upstream API usage.