API-Referenz
Endpoints, parameters, and response schemas. Every endpoint returns teaser content for free — pay per query to unlock full analysis.
1 SOL = 1,000,000 credits | x402/USDC pricing applies per-request
Authentifizierung
Every endpoint returns teaser content (headline, lead, image) for free. To unlock full content (body, key facts, structured data), include a payment header with your request.
Prepaid Credits (recommended)
Buy credits with SOL, then include your wallet address. Credits are deducted per request.
X-Credits-Wallet: YOUR_SOLANA_WALLET_ADDRESS
x402/USDC via CDP Facilitator
Standard x402 flow. Sign a payment payload with your Solana wallet. Settles in USDC.
payment-signature: BASE64_ENCODED_PAYMENT_SIGNATURE
Direct SOL Payment (legacy)
Transfer SOL to the receiving wallet, then include the transaction signature.
X-Payment: SOLANA_TX_SIGNATURE
Discovery
Any premium endpoint called without payment headers returns 402 Payment Required with pricing information in response headers including the x402-compliant payment-required header.
Free Tier
FreeTeaser-Inhalte (Headline, Lead, Bild, Klassifikation) erfordern keine Authentifizierung und keine Zahlung.
Rate limit: 60 requests/minute | No headers required
/api/items
Latest central bank publications, paginated. Returns items sorted by publication date (newest first).
Parameter
| Name | Type | Description |
|---|---|---|
| page | optional | Page number (Standard: 1) |
| per_page | optional | Items per page, 1-100 (Standard: 20) |
| institution | optional | Filter by institution code (e.g. ECB) |
| locale | optional | Filter by locale (en, de) |
Antwort 200
{
"items": [
{
"id": 12345,
"slug": "ecb-rate-cut-january-2026",
"title": "Monetary policy decisions",
"headline": "ECB cuts interest rate to 2.75 percent",
"institution_code": "ECB",
"category": "Press",
"locale": "en",
"published_at": "2026-01-08T14:00:00"
}
],
"total": 12500,
"page": 1,
"per_page": 20
}
/api/item/{slug}
Single item with full detail including headline, lead, key facts, and classification.
Parameter
| Name | Type | Description |
|---|---|---|
| slug | erforderlich | Item slug (path parameter) |
Antwort 200
{
"id": 12345,
"slug": "ecb-rate-cut-january-2026",
"title": "Monetary policy decisions",
"headline": "ECB cuts interest rate to 2.75 percent",
"lead": "The ECB has reduced its key rate by 25bp...",
"institution_code": "ECB",
"category": "Press",
"key_facts": [
{ "label": "New Rate", "value": "2.75%", "change": "-0.25pp" }
],
"published_at": "2026-01-08T14:00:00",
"source_url": "https://ecb.europa.eu/..."
}
/api/semantic-search
Free semantic search with a limit of 50 results. Uses vector embeddings for relevance ranking.
Parameter
| Name | Type | Description |
|---|---|---|
| q | erforderlich | Search query (3-500 chars) |
| locale | optional | Filter by locale (en, de) |
| limit | optional | Max results, 1-50 (Standard: 20) |
Antwort 200
{
"query": "inflation forecast",
"items": [
{
"id": 12345,
"slug": "ecb-rate-cut-january-2026",
"title": "Monetary policy decisions",
"headline": "ECB cuts interest rate to 2.75 percent",
"lead": "The ECB has reduced...",
"institution_code": "ECB",
"similarity": 0.9234,
"published_at": "2026-01-08T14:00:00"
}
],
"total": 5
}
/api/rag-context
RAG-optimized context for LLM consumption. Returns documents with body text within a token budget (max 2000 tokens).
Parameter
| Name | Type | Description |
|---|---|---|
| q | erforderlich | Query (3-500 chars) |
| locale | optional | Filter by locale |
| max_tokens | optional | Token budget, 100-2000 (Standard: 2000) |
Antwort 200
{
"query": "ECB monetary policy 2026",
"items": [
{
"id": 12345,
"headline": "ECB cuts interest rate to 2.75 percent",
"lead": "The ECB has reduced...",
"body_text": "Full section text...",
"institution": "European Central Bank",
"similarity": 0.9234
}
],
"total_tokens_estimate": 1800
}
Credit-Verwaltung
/api/credits/purchase
Buy credits by sending SOL to the receiving wallet and verifying the transaction.
Rate limit: 10 requests/minute per wallet
Request Body
{
"tx_signature": "5UfD...base58-encoded-signature",
"wallet": "YourSolanaWalletAddress"
}
Antwort 200
{
"credits_granted": 1000,
"new_balance": 1000,
"amount_lamports": 1000000,
"credits_per_sol": 1000000
}
Fehlercodes
| Code | Description |
|---|---|
| 400 | Invalid wallet, failed TX verification, duplicate signature, payment too small |
| 429 | Rate limit exceeded (10/min per wallet) |
| 503 | Payment system not enabled or not configured |
/api/credits/balance
Check credit balance for a wallet.
Parameter
| Name | Type | Description |
|---|---|---|
| wallet | erforderlich | Solana wallet address (32-64 chars) |
Antwort 200
{
"wallet": "YourSolanaWalletAddress",
"balance": 850,
"total_purchased": 1000,
"total_spent": 150
}
Tier 1: Metadaten
1 credit/api/premium/institutions
Institution listing with feed status and item counts.
Antwort 200
{
"institutions": [
{
"code": "ECB",
"name": "European Central Bank",
"active": true,
"total_items": 1234,
"published_items": 1100,
"failed_items": 12,
"latest_item_at": "2026-02-15T14:30:00"
}
],
"total": 30
}
/api/premium/feed-status
Pipeline throughput and health metrics.
Antwort 200
{
"daily_stats": [
{
"day": "2026-02-15",
"items": 47,
"institutions": 18
}
],
"pipeline_status": {
"published": 12500,
"enriched": 200,
"extracted": 50,
"failed": 30
}
}
Tier 2: Strukturierte Daten
10 credits/api/premium/rates
Key interest rates and economic indicators extracted from central bank publications.
Parameter
| Name | Type | Description |
|---|---|---|
| institution | optional | Filter by institution code (e.g. ECB) |
Antwort 200
{
"rates": [
{
"institution": "ECB",
"institution_name": "European Central Bank",
"label": "Deposit Rate",
"value": "2.75%",
"change": "-0.25pp",
"source_date": "2026-02-10T14:00:00"
}
],
"total": 45
}
/api/premium/sentiment
Policy stance indicators from recent central bank communications.
Parameter
| Name | Type | Description |
|---|---|---|
| institution | optional | Filter by institution code |
| days | optional | Lookback period, 1-30 (Standard: 7) |
Antwort 200
{
"sentiments": [
{
"institution": "FED",
"institution_name": "Federal Reserve",
"category": "Speech",
"communication_type": "policy_guidance",
"policy_areas": ["monetary_policy", "inflation"],
"headline": "Powell: Inflation progress continues",
"published_at": "2026-02-14T18:00:00"
}
],
"total": 12,
"period_days": 7
}
/api/premium/image/{item_id}
Image metadata and available format URLs for a published item. Returns JSON with all available image formats and their dimensions.
Parameter
| Name | Type | Description |
|---|---|---|
| item_id | erforderlich | Item ID (path parameter) |
Antwort 200
{
"item_id": 12345,
"slug": "ecb-rate-cut-january-2026",
"formats": [
{
"format": "hero",
"width": 1280,
"height": 720,
"url": "/api/premium/image/12345/hero"
},
{
"format": "og",
"width": 1200,
"height": 630,
"url": "/api/premium/image/12345/og"
},
{
"format": "thumb",
"width": 400,
"height": 225,
"url": "/api/premium/image/12345/thumb"
}
]
}
/api/premium/image/{item_id}/{format}
Redirect to the actual image asset URL for the specified format. Returns a 302 redirect to the CMS-hosted image.
Parameter
| Name | Type | Description |
|---|---|---|
| item_id | erforderlich | Item ID (path parameter) |
| format | erforderlich | Image format: hero (1280×720), og (1200×630), thumb (400×225) |
Antwort 302
# Response: 302 Found Location: https://cms.state-of.biz/assets/12345-hero.webp Content-Type: image/webp
Tier 3: Semantische Objekte
100 credits/api/premium/semantic-search
Semantic vector search across central bank documents using embeddings.
Parameter
| Name | Type | Description |
|---|---|---|
| q | erforderlich | Search query (3-500 chars) |
| locale | optional | Filter by locale (en, de) |
| institution | optional | Filter by institution code |
| limit | optional | Max results, 1-100 (Standard: 20) |
Antwort 200
{
"query": "ECB interest rate decision",
"items": [
{
"id": 12345,
"slug": "ecb-rate-cut-january-2026",
"url": "https://ecb.europa.eu/...",
"title": "ECB announces interest rate decision",
"headline": "ECB cuts interest rate to 2.75 percent",
"lead": "The ECB has reduced its key rate by 25bp...",
"institution_code": "ECB",
"institution_name": "European Central Bank",
"similarity": 0.9234,
"published_at": "2026-01-08T14:00:00"
}
],
"total": 5
}
/api/premium/rag-context
RAG-optimized context with full content for LLM consumption. Returns documents with body text within a token budget.
Parameter
| Name | Type | Description |
|---|---|---|
| q | erforderlich | Query (3-500 chars) |
| locale | optional | Filter by locale |
| max_tokens | optional | Token budget, 100-16000 (Standard: 4000) |
Antwort 200
{
"query": "ECB monetary policy 2026",
"items": [
{
"id": 12345,
"headline": "ECB cuts interest rate to 2.75 percent",
"lead": "The ECB has reduced...",
"body_text": "Full section text...",
"institution": "European Central Bank",
"published_at": "2026-01-08",
"source_url": "https://ecb.europa.eu/...",
"similarity": 0.9234
}
],
"total_tokens_estimate": 3200
}
/api/premium/briefing
Full item analysis with all enrichment data — headline, body, key facts, classification, processing metadata.
Parameter
| Name | Type | Description |
|---|---|---|
| item_id | erforderlich | Item ID |
| locale | optional | Locale (Standard: en) |
Antwort 200
{
"id": 12345,
"slug": "ecb-rate-cut-january-2026",
"url": "https://ecb.europa.eu/...",
"title": "ECB announces interest rate decision",
"institution_code": "ECB",
"institution_name": "European Central Bank",
"published_at": "2026-01-08T14:00:00",
"content": {
"headline": "ECB cuts interest rate to 2.75 percent",
"lead": "...",
"body": { "section_1": {...} },
"quote": {
"text": "...",
"speaker": "Christine Lagarde",
"role": "ECB President"
},
"key_facts": [
{ "label": "New Rate", "value": "2.75%", "change": "-0.25pp" }
]
},
"classification": {
"category": "Press",
"communication_type": "policy_decision",
"policy_areas": ["monetary_policy", "interest_rates"]
},
"processing": {
"model": "gemini-2.5-flash",
"prompt_version": "v1.0",
"duration_ms": 3200
}
}
/api/premium/image-feed
Latest published images as a JSON feed. Ideal for building visual dashboards or social media integrations.
Parameter
| Name | Type | Description |
|---|---|---|
| limit | optional | Max results, 1-100 (Standard: 20) |
| institution | optional | Filter by institution code |
| locale | optional | Locale (Standard: en) |
Antwort 200
{
"images": [
{
"item_id": 12345,
"slug": "ecb-rate-cut-january-2026",
"headline": "ECB cuts interest rate to 2.75 percent",
"institution_code": "ECB",
"published_at": "2026-01-08T14:00:00",
"formats": {
"hero": "/api/premium/image/12345/hero",
"og": "/api/premium/image/12345/og",
"thumb": "/api/premium/image/12345/thumb"
}
}
],
"total": 20
}
Tier 4: Composite Reports
1,000 credits/api/premium/cross-institution
Multi-institution comparison report. Compare recent communications across central banks.
Parameter
| Name | Type | Description |
|---|---|---|
| institutions | erforderlich | Comma-separated codes, max 10 (e.g. ECB,FED,BOE) |
| days | optional | Lookback period, 1-30 (Standard: 7) |
| locale | optional | Locale (Standard: en) |
Antwort 200
{
"institutions": [
{
"institution_code": "ECB",
"institution_name": "European Central Bank",
"items": [
{
"id": 12345,
"headline": "ECB cuts rate to 2.75%",
"lead": "...",
"category": "Press",
"policy_areas": ["monetary_policy"],
"key_facts": [...],
"published_at": "2026-02-10T14:00:00"
}
]
}
],
"period_days": 7,
"total_items": 25
}
/api/premium/weekly-digest
Weekly summary organized by category and institution.
Parameter
| Name | Type | Description |
|---|---|---|
| locale | optional | Locale (Standard: en) |
| institution | optional | Filter by institution code |
Antwort 200
{
"period": "7 days",
"total_items": 150,
"by_category": {
"Press": [
{
"id": 12345,
"headline": "...",
"institution": "ECB",
"key_facts": [...],
"published_at": "2026-02-14T14:00:00"
}
],
"Speech": [...]
},
"by_institution": {
"ECB": [...],
"FED": [...]
}
}
Fehlercodes
| Code | Status | Description |
|---|---|---|
| 400 | Bad Request | Invalid parameters, wallet format, failed TX verification, duplicate signature |
| 401 | Unauthorized | API key required (admin endpoints only) |
| 402 | Payment Required | No valid payment provided. Response headers contain pricing and wallet information. |
| 404 | Not Found | Item or resource not found |
| 429 | Rate Limited | Too many requests (10/min credit purchase, 60/min API) |
| 503 | Unavailable | Service temporarily unavailable (payment system, embeddings, pgvector) |
402 Response Headers
When a premium endpoint returns 402, these headers provide payment instructions:
# x402-compliant (Base64-encoded JSON) payment-required: eyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOi4uLn0= # Credit system headers X-Credits-Cost: 100 X-Credits-Per-Sol: 1000000 X-Wallet: 3RenNv83puYmmGAjCW1MXVdeDHfg4fHo7zK8nMfF8FPP X-Network: mainnet-beta # Direct payment headers X-Price: 0.001 X-Price-Lamports: 1000000
Decoded payment-required Payload
The payment-required header is a Base64-encoded JSON object conforming to the x402 protocol specification:
{
"scheme": "exact",
"network": "solana",
"maxAmountRequired": "1000",
"resource": "https://state-of.biz/api/premium/semantic-search?q=ECB",
"description": "Semantic vector search across central bank documents",
"mimeType": "application/json",
"payTo": "3RenNv83puYmmGAjCW1MXVdeDHfg4fHo7zK8nMfF8FPP",
"asset": {
"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"decimals": 6,
"symbol": "USDC"
}
}
The maxAmountRequired is in atomic USDC units (6 decimals). Divide by 106 for the USD amount. Any x402-compatible client or MCP agent can read this payload and handle payment automatically.