API Reference

Endpoints, parameters, and response schemas. Every endpoint returns teaser content for free — pay per query to unlock full analysis.

Base URL

https://state-of.biz

Interactive Explorer

/api/docs

Tier 1

credits/request

$0.00001 USDC

Tier 2

credits/request

$0.0001 USDC

Tier 3

100

credits/request

$0.001 USDC

Tier 4

1,000

credits/request

$0.01 USDC

1 SOL = 1,000,000 credits | x402/USDC pricing applies per-request

Authentication

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

Free

Teaser content (headline, lead, image, classification) requires no authentication or payment.

Rate limit: 60 requests/minute | No headers required

GET /api/items

Latest central bank publications, paginated. Returns items sorted by publication date (newest first).

Parameters

Name	Type	Description
page	optional	Page number (default: 1)
per_page	optional	Items per page, 1-100 (default: 20)
institution	optional	Filter by institution code (e.g. `ECB`)
locale	optional	Filter by locale (`en`, `de`)

Response `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
}

GET /api/item/{slug}

Single item with full detail including headline, lead, key facts, and classification.

Parameters

Name	Type	Description
slug	required	Item slug (path parameter)

Response `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/..."
}

GET /api/semantic-search

Free semantic search with a limit of 50 results. Uses vector embeddings for relevance ranking.

Parameters

Name	Type	Description
q	required	Search query (3-500 chars)
locale	optional	Filter by locale (`en`, `de`)
limit	optional	Max results, 1-50 (default: 20)

Response `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
}

GET /api/rag-context

RAG-optimized context for LLM consumption. Returns documents with body text within a token budget (max 2000 tokens).

Parameters

Name	Type	Description
q	required	Query (3-500 chars)
locale	optional	Filter by locale
max_tokens	optional	Token budget, 100-2000 (default: 2000)

Response `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 Management

POST /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"
}

Response `200`

{
  "credits_granted": 1000,
  "new_balance": 1000,
  "amount_lamports": 1000000,
  "credits_per_sol": 1000000
}

Error Codes

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

GET /api/credits/balance

Check credit balance for a wallet.

Parameters

Name	Type	Description
wallet	required	Solana wallet address (32-64 chars)

Response `200`

{
  "wallet": "YourSolanaWalletAddress",
  "balance": 850,
  "total_purchased": 1000,
  "total_spent": 150
}

Tier 1: Metadata

1 credit

GET /api/premium/institutions

Institution listing with feed status and item counts.

Response `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
}

GET /api/premium/feed-status

Pipeline throughput and health metrics.

Response `200`

{
  "daily_stats": [
    {
      "day": "2026-02-15",
      "items": 47,
      "institutions": 18
    }
  ],
  "pipeline_status": {
    "published": 12500,
    "enriched": 200,
    "extracted": 50,
    "failed": 30
  }
}

Tier 2: Structured Data

10 credits

GET /api/premium/rates

Key interest rates and economic indicators extracted from central bank publications.

Parameters

Name	Type	Description
institution	optional	Filter by institution code (e.g. `ECB`)

Response `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
}

GET /api/premium/sentiment

Policy stance indicators from recent central bank communications.

Parameters

Name	Type	Description
institution	optional	Filter by institution code
days	optional	Lookback period, 1-30 (default: 7)

Response `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
}

GET /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.

Parameters

Name	Type	Description
item_id	required	Item ID (path parameter)

Response `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"
    }
  ]
}

GET /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.

Parameters

Name	Type	Description
item_id	required	Item ID (path parameter)
format	required	Image format: `hero` (1280×720), `og` (1200×630), `thumb` (400×225)

Response `302`

# Response: 302 Found
Location: https://cms.state-of.biz/assets/12345-hero.webp
Content-Type: image/webp

Tier 3: Semantic Objects

100 credits

GET /api/premium/semantic-search

Semantic vector search across central bank documents using embeddings.

Parameters

Name	Type	Description
q	required	Search query (3-500 chars)
locale	optional	Filter by locale (`en`, `de`)
institution	optional	Filter by institution code
limit	optional	Max results, 1-100 (default: 20)

Response `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
}

GET /api/premium/rag-context

RAG-optimized context with full content for LLM consumption. Returns documents with body text within a token budget.

Parameters

Name	Type	Description
q	required	Query (3-500 chars)
locale	optional	Filter by locale
max_tokens	optional	Token budget, 100-16000 (default: 4000)

Response `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
}

GET /api/premium/briefing

Full item analysis with all enrichment data — headline, body, key facts, classification, processing metadata.

Parameters

Name	Type	Description
item_id	required	Item ID
locale	optional	Locale (default: `en`)

Response `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
  }
}

GET /api/premium/image-feed

Latest published images as a JSON feed. Ideal for building visual dashboards or social media integrations.

Parameters

Name	Type	Description
limit	optional	Max results, 1-100 (default: 20)
institution	optional	Filter by institution code
locale	optional	Locale (default: `en`)

Response `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

GET /api/premium/cross-institution

Multi-institution comparison report. Compare recent communications across central banks.

Parameters

Name	Type	Description
institutions	required	Comma-separated codes, max 10 (e.g. `ECB,FED,BOE`)
days	optional	Lookback period, 1-30 (default: 7)
locale	optional	Locale (default: `en`)

Response `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
}

GET /api/premium/weekly-digest

Weekly summary organized by category and institution.

Parameters

Name	Type	Description
locale	optional	Locale (default: `en`)
institution	optional	Filter by institution code

Response `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": [...]
  }
}

Error Codes

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 10⁶ for the USD amount. Any x402-compatible client or MCP agent can read this payload and handle payment automatically.

API Reference

Authentication

Prepaid Credits (recommended)

x402/USDC via CDP Facilitator

Direct SOL Payment (legacy)

Discovery

Free Tier

Parameters

Response 200

Parameters

Response 200

Parameters

Response 200

Parameters

Response 200

Credit Management

Request Body

Response 200

Error Codes

Parameters

Response 200

Tier 1: Metadata

Response 200

Response 200

Tier 2: Structured Data

Parameters

Response 200

Parameters

Response 200

Parameters

Response 200

Parameters

Response 302

Tier 3: Semantic Objects

Parameters

Response 200

Parameters

Response 200

Parameters

Response 200

Parameters

Response 200

Tier 4: Composite Reports

Parameters

Response 200

Parameters

Response 200

Error Codes

402 Response Headers

Decoded payment-required Payload

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `302`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Decoded `payment-required` Payload