Home › Developers › 📡 API Reference
📡 API Reference

Every endpoint. Every response.

Complete reference for the ForceDream Intelligence OS API. Base URL: api.forcedream.ai. Bearer token auth.

// Authentication

Bearer token

All requests require an Authorization header with your Bearer key. Get yours free at forcedream.com/earn.

All requests
Authorization: Bearer sk_fd_your_key_here
Base URL: https://api.forcedream.ai  ·  Region: lhr1 (London)  ·  Format: JSON
// Core routes

Signup & account

POST/api/signupCreate account & get API key

Create a free account and receive a Bearer API key. The key is shown once — save it immediately.

Request
curl -X POST https://api.forcedream.ai/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
Response 201
{
  "api_key": "sk_fd_...",
  "user_id": "usr_...",
  "balance_pence": 0,
  "referral_code": "abc123",
  "next_step": "/v1/earn/1"
}
GET/v1/balanceCurrent balance & earnings
Response 200
{
  "balance_pence": 546,
  "balance_gbp": "£5.46",
  "total_earned_pence": 546,
  "withdrawal_eligible": true,
  "withdrawal_minimum_gbp": "£5.00"
}
POST/v1/withdrawWithdraw to Stripe — requires £5 minimum
Connect your Stripe account first: GET /account/connect
Response 200
{
  "success": true,
  "withdrawn_pence": 546,
  "withdrawn_gbp": "£5.46",
  "worm_seal": "c2e91c81...",
  "settlement": "Transfer initiated. Funds arrive within 1 business day."
}
GET/account/connectConnect Stripe account for withdrawals

Redirects to Stripe OAuth. After completing, your stripe_account_id is stored and withdrawals work automatically.

GET/account/statusAccount connection status
Response 200
{
  "stripe_connected": true,
  "balance_gbp": "£0.78",
  "total_earned_gbp": "£0.78",
  "withdrawal_eligible": false
}
// AI routing

Route & earn

POST/v1/routeRoute task to cheapest capable model
{
  "task": "summarise",         // task type — used for model selection
  "input": "Your content",    // content to process
  "quality": "auto",          // "auto"|"high"|"low" (optional)
  "max_cost_pence": 100       // budget cap (optional)
}
{
  "result": "...",
  "model_used": "claude-haiku",
  "cost_pence": 0.04,
  "earned_pence": 0.78,
  "latency_ms": 1240,
  "worm_seal": "7b62..."
}
POST/v1/earn/1Complete a task and earn 78p

Complete one of 5 pre-defined tasks and earn exactly 78p credited to your balance.

Request
{"task": "summarise_sentence"} // or translate_hello, classify_sentiment, name_three_things, one_word_summary
// Platform modules

Subsystems (GET /info)

Every module exposes a GET /info route returning its layer, capabilities, and Redis wiring status.

ModuleRoute prefixLayerStatus
Memory Engine/v1/memory/*L501Live
Safety Engine/v1/safety/*L401Live
Routing Engine/v1/routeL251Live
Agent Runtime/v1/agents/*L601Live
WORM Audit/v1/audit/*L0Live
Logs SDK/v1/logs/*L502Live
Fraud Detection/v1/fraud/*L402Live
A2A Payments/v1/a2a/*L602Live
Eval System/v1/eval/*L503Live
Observability/v1/observability/*L504Live
Credits/v1/credits/*L0Live
Search Engine/v1/search/*L600Live
Dispatch/v1/dispatch/*L600Live
Identity/KYC/v1/identity/*L50Live
Billing Engine/v1/billing/*L600Live
Workspaces/v1/enterprise/*L563Live
Skip to content Skip to content Skip to content
Home › Developers
ForceDream Developer Platform

Build agents that
earn you 80%.

The first agentic AI platform where the developer earnings floor is enforced in platform rules code — not a contract. 80% to you. Immutable. WORM-sealed on every transaction.

🚀 Start in 5 minutes API Reference → Free account →
80%
// your earnings [L828]
595+
// platform layers
33
// M2M bridges
<5 min
// to first deploy
// 01 — Quick start

Deploy your first agent in 5 minutes

No configuration files. No Kubernetes. One command from signup to earning.

1
Install the SDK
Works on Python 3.8+ and Node 18+. No binary dependencies.
pip install forcedream
npm install @forcedream/sdk
2
Set your API key
Get your key at forcedream.com/account. Free forever — no credit card required.
export FD_API_KEY="fd_live_..."
import os
os.environ["FD_API_KEY"] = "fd_live_..."
const client = new ForceDream({ apiKey: "fd_live_..." });
3
Make your first API call
Call the inference gateway. Routes to the cheapest available provider automatically.
from forcedream import ForceDreamClient

client = ForceDreamClient()  # reads FD_API_KEY from env

response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
# 80% of the fee goes to you [CONSTITUTION: L828]
import { ForceDreamClient } from "@forcedream/sdk";

const client = new ForceDreamClient();

const response = await client.chat.completions.create({
  model: "llama-3.3-70b-versatile",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);
curl https://api.forcedream.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $FD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role":"user","content":"Hello!"}]
  }'
4
Deploy your agent
Push to the marketplace. Start earning immediately. 80% of every call goes to you.
terminal 
fd deploy my-agent --name "My Inference Agent" --price 0.10
✅ Agent deployed: https://api.forcedream.ai/agents/my-agent
   Earnings floor: 80% [CONSTITUTION: L828-FLOOR]
   Dream Tax: 2.5% [CONSTITUTION: L828-DT]
   Every call earns you: £0.08 per query
Full quickstart guide →
// 02 — What you can build

The agentic AI economy, built by you

Every product earns you 80%. Enforced by L828-IMMUTABLE — the constitution cannot be changed by ForceDream, investors, or anyone else.

// Inference
AI Inference Agent
Route requests to Groq, Cerebras, Anthropic, OpenAI. Auto-failover. Sell at £0.10/call.
↑ £0.08 per call (80%)
// Payments
Payment Agent
Accept Stripe, PawaPay, MTN MoMo. Deploy in one command. Global from day one.
↑ 80% of every transaction fee
// Data
Data Oracle
Sell sentiment data, fraud signals, lead scores via HTTP 402. External agents pay automatically.
↑ £0.02–£2.00 per query (80%)
// Security
Security Agent
Vulnerability scanning, fraud detection, KYC verification. £0.75/scan to your pocket.
↑ £0.60 per scan (80%)
// Code
Code Generation API
Wrap any LLM in an HTTP 402 paywall. Other agents pay to use your code generation endpoint.
↑ £0.40 per call (80%)
// Automation
Task Automation Agent
Build autonomous workflows. Sell executions. Every completed task WORM-sealed.
↑ Custom pricing, always 80%
// 03 — Core API

REST API reference

Base URL: https://api.forcedream.ai/api/v1. All endpoints return JSON.

All requests require Authorization: Bearer <FD_API_KEY>. Keys available at forcedream.com/account.
MethodEndpointDescription
POST/chat/completionsOpenAI-compatible LLM inference. 15 providers, auto-failover.
GET/modelsList all available models across active providers.
GET/healthPlatform health check. Returns status + provider count.
POST/oracle/{bridge}Call a data bridge. Returns 402 + payment link if unpaid.
GET/bridgesList all 33 data bridges with prices.
GET/reputationVerifiable WORM-based proof of platform work.
POST/checkout/sessionCreate a Stripe Checkout session for a marketplace product.
POST/notifySave email for coming-soon product notification.
POST/agents/deployDeploy an agent to the marketplace.
GET/agents/{id}/earningsGet earnings for a specific agent. Requires auth.
POST/webhooks/testSend a test webhook event to your registered endpoint.
Full API reference →
// 04 — SDKs

Official client libraries

All SDKs are OpenAI API-compatible. Drop-in replacement — change the base URL and API key.

Pythonv1.0.0
Python 3.8+
pip install forcedream
JavaScript / TSv1.0.0
Node 18+ · Browser
npm i @forcedream/sdk
Gov1.0.0
Go 1.21+
go get github.com/forcedreamai/fd-go
Rubyv1.0.0
Ruby 3.0+
gem install forcedream
SDK documentation →
// 05 — Earnings

Calculate your earnings

Every transaction enforces L828-IMMUTABLE. DT = 2.5% · Platform = 17.5% · You keep 80%.

Monthly API calls
Price per call (£)
platform rules split [L828]:
DT: 2.5% · Platform: 17.5% · You: 80%
GROSS REVENUE £1,000.00
DREAM TAX (2.5%) −£25.00
PLATFORM FEE (17.5%) −£175.00
YOUR EARNINGS (80%) £800.00
Full earnings guide →
// 06 — Webhooks

Real-time events

Register your endpoint at app.forcedream.ai/webhooks. All events are HMAC-SHA256 signed.

agent.deployed Fired when an agent successfully deploys to the marketplace.
json payload
{
  "event": "agent.deployed",
  "timestamp": 1714391200,
  "data": {
    "agent_id": "ag_01jtest",
    "name": "My Inference Agent",
    "price_gbp": 0.10,
    "earn_rate": 0.80,
    "constitution": "L828-IMMUTABLE"
  }
}
payout.completed Fired when an earnings payout is sent to your account.
json payload
{
  "event": "payout.completed",
  "timestamp": 1714391200,
  "data": {
    "payout_id": "po_01jtest",
    "amount_gbp": 800.00,
    "earn_rate": 0.80,
    "dream_tax_pence": 2500,
    "worm_sealed": true
  }
}
billing.split Fired on every API call with the platform rules revenue split.
json payload
{
  "event": "billing.split",
  "data": {
    "gross_pence": 10,
    "dt_pence": 1,        // 2.5% [L828-DT]
    "platform_pence": 2,  // 17.5% [L828-PLATFORM]
    "agent_pence": 8,     // 80% [L828-FLOOR]
    "constitution": "L828-IMMUTABLE"
  }
}
fraud.detected Fired when the platform detects suspicious activity on your agent.
json payload
{
  "event": "fraud.detected",
  "data": {
    "agent_id": "ag_01jtest",
    "ip": "1.2.3.4",
    "risk_score": 0.92,
    "action": "blocked"
  }
}
Webhook reference →
// 07 — Rate limits

Rate limits & tiers

All limits are per API key. Limits reset every minute. Headers included on every response.

Free
100
req / minute
2,000 req/hour
Free forever
All endpoints
Community support
Pro
1,000
req / minute
60,000 req/hour
Priority routing
Webhook support
Email support
Enterprise
∞
custom SLA
Dedicated cluster
Custom limits
SLA guarantee
Slack support
X-RateLimit-Limit-Minute: 100
X-RateLimit-Remaining-Minute: 94
X-RateLimit-Reset: 1714391260
// 08 — Error codes

Error reference

All errors return JSON with {"error":"message","code":"EXXXX"}.

E001
API key invalid
Regenerate at forcedream.com/account. Check for trailing whitespace.
E002
Rate limit exceeded
Retry after X-RateLimit-Reset timestamp. Upgrade at /pricing.
E003
Payment required (402)
Complete payment via payment.payment_link in response body.
E004
Model not found
Check GET /api/v1/models for available model IDs.
E005
Provider unavailable
All providers for this model are down. Auto-retry or choose alternate model.
E006
Webhook signature invalid
Recompute HMAC-SHA256 of raw body with FD_WEBHOOK_SECRET.
E007
Agent not found
Verify agent_id. Check it is deployed and not disabled.
E008
platform rules violation
Request violates L828-IMMUTABLE. Earnings split or DT cannot be overridden.
E009
Stripe key missing
Add STRIPE_SECRET_KEY (sk_live_...) to .env. Check env_loader load order.
E010
WORM seal exists
Transaction already WORM-sealed. Cannot be modified. Use idempotency key to deduplicate.
Full error reference →
// 09 — Community

Build with us

The ForceDream developer community across Slack, GitHub, and Twitter.

💬
Slack
Developer community
🐙
GitHub
Open source + SDKs
𝕏
Twitter / X
Updates + releases