>_ Premium API for AI Agents

Pay in USDC on Base. Get aggregated real-time data, one call at a time.

The free TerminalFeed API is staying free. Premium is a separate, additive tier for AI agents and applications that need composed multi-source payloads in a single request: macro indicators with forex and commodities, crypto with on-chain network stats, world briefings with prediction-market context. The credits work on TensorFeed.ai too. One purchase, both data sources.

Access on the network (Agent Fair-Trade)

TerminalFeed is the second adopter of the Agent Fair-Trade Agreement (AFTA) after TensorFeed. The agreement enforces three guarantees in code: automatic no-charge on 5xx, billing breaker, schema fail, and stale data; Ed25519-signed receipts on every paid call; a public on-chain payment rail (USDC on Base).

Reciprocal access is the user-visible payoff. A bearer token minted on either site spends on either site. The credit ledger lives on TensorFeed; TerminalFeed validates and charges through the cross-Worker AFTA rail (POST /api/internal/validate then POST /api/internal/commit). Each site signs its own receipts with its own keypair, fetched from its own /.well-known/.

• Manifest: /.well-known/agent-fair-trade.json
• Public Ed25519 key: /.well-known/terminalfeed-receipt-key.json
• Verify a receipt: POST /api/receipt/verify
• Public no-charge ledger: /api/payment/no-charge-stats
• Per-endpoint freshness SLAs and AFTA status: /api/meta
• Sister-site manifest: tensorfeed.ai/.well-known/agent-fair-trade.json

Quick Start

Three steps to start querying premium endpoints. No SDK required in v1; standard HTTP works fine.

1. Buy credits (returns wallet, memo, quote)

curl -X POST https://terminalfeed.io/api/payment/buy-credits \
  -H "Content-Type: application/json" \
  -d '{"amount_usd": 1.00}'

# Response
{
  "wallet": "0x...",
  "memo": "tf_buy_a1b2c3...",
  "quote": { "amount_usd": 1.00, "credits": 50, "chain": "base" },
  "expires_at": "2026-04-27T18:30:00Z"
}

2. Send USDC to the wallet on Base mainnet

Use any wallet that supports Base and USDC. Include the memo as a transaction note where supported, or just keep the tx hash. Both work.

3. Confirm the payment, receive your bearer token

curl -X POST https://terminalfeed.io/api/payment/confirm \
  -H "Content-Type: application/json" \
  -d '{"tx_hash": "0xabc...", "nonce": "tf_buy_a1b2c3..."}'

# Response
{
  "token": "tf_live_<64-char-hex>",
  "credits": 50
}

4. Call any premium endpoint

curl https://terminalfeed.io/api/pro/macro \
  -H "Authorization: Bearer tf_live_<64-char-hex>"

# Response includes the composed payload plus a header:
#   X-Credits-Remaining: 48

Endpoints

ctx = tf.get("/api/pro/agent-context")
client.messages.create(
    model="claude-opus-4-7",
    system=ctx["system_prompt"],   # paste-ready
    messages=[{"role": "user", "content": "..."}]
)

Pricing

Each successful premium response returns the remaining credit count in an X-Credits-Remaining header. You can also poll GET /api/payment/balance with your bearer token any time.

Published Wallet

The same wallet TensorFeed publishes. Cross-verified at four locations: this page, /terms, /llms.txt, and the GitHub repo README. If any disagree, do not send funds. Email [email protected].

Authentication

Pass your bearer token in the Authorization header on every premium call:

Authorization: Bearer tf_live_<64-char-hex>

Tokens are bearer credentials. Treat them like API keys. Store securely. Do not commit them. Rotate by purchasing a new pack and abandoning the old token if compromised. Replay protection is server-side; the same purchase nonce or tx hash will not credit twice.

Failure modes (HTTP 402 Payment Required)

Atomic Charge Property

Credits are decremented before the upstream fetch begins. If TerminalFeed's upstream sources partially fail, you still receive a 200 response with whatever data we successfully composed, and the credit still counts. The credit pays for the routing decision and the aggregation work, not a guaranteed upstream success. This matches TensorFeed's existing model. We monitor upstream reliability and will surface degraded sections in a warning field on partial responses.

License (Inference Only)

Refund Policy

All credit purchases are final and non-refundable. Credits never expire, however, so they remain spendable indefinitely on terminalfeed.io and tensorfeed.ai. We recommend buying in small amounts ($1 = 50 credits) until you have a feel for your call volume, then topping up as needed.

Cross-Site Bundle

Credits and bearer tokens are jointly redeemable on terminalfeed.io and tensorfeed.ai. One USDC purchase, two data sources. The TensorFeed payment Worker is the system of record; TerminalFeed authenticates each premium call against it via an internal contract. Same wallet, same chain, shared credit pool. See the TensorFeed agent payments page for the parallel surface.

Webhooks (Push Instead of Poll)

Register a webhook URL to receive push deliveries every ~5 minutes from any of the 9 premium endpoints. Each fire costs 1 credit ($0.02), HMAC-SHA256 signed, with auto-pause on insufficient_credits. Per-token cap: 5 active subscriptions.

Create

curl -X POST https://terminalfeed.io/api/pro/subscribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tf_live_<64-char-hex>" \
  -d '{"endpoint":"world-deltas","webhook_url":"https://your-server.example/hook"}'

# Response (save the secret; not returned again):
{
  "id": "wh_<16-char-hex>",
  "secret": "whsec_<32-char-hex>",
  "hmac_algorithm": "sha256",
  "fire_cost_credits": 1,
  "fire_interval": "~5 minutes (cron */5 * * * *)",
  ...
}

Delivery contract

Every ~5 minutes you receive a POST application/json:

POST /your/hook
Content-Type: application/json
X-TerminalFeed-Signature: sha256=<hex>
X-TerminalFeed-Timestamp: 1714261771
X-TerminalFeed-Subscription: wh_eb1db371f08ba2ed
User-Agent: terminalfeed-webhook/1.0

{
  "subscription_id": "wh_eb1db371f08ba2ed",
  "endpoint": "world-deltas",
  "delivered_at": "2026-04-28T00:30:00.000Z",
  "data": { ... full endpoint payload ... }
}

Verify the signature

import hmac, hashlib

def verify(secret, signature_header, timestamp_header, raw_body):
    sig = signature_header.split("=", 1)[-1]
    expected = hmac.new(
        secret.encode(),
        f"{timestamp_header}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

Cancel anytime: DELETE /api/pro/subscribe/<id> with your bearer. List active: GET /api/pro/subscriptions.

Why this exists: a monitor agent polling /api/pro/world-deltas every 5 minutes pays 2 credits per cycle ($0.04). A webhook subscription pays 1 credit per fire ($0.02), pushed instead of pulled, with no client-side polling loop. Half the cost, half the infrastructure.

MCP Server (Claude Desktop, Claude Code, any MCP client)

TerminalFeed runs a Model Context Protocol server at https://terminalfeed.io/api/mcp. All 21 tools (9 free + 9 premium + 3 payment) are exposed natively. The bearer token doubles as the MCP credential.

Claude Desktop config (paste into claude_desktop_config.json):

{
  "mcpServers": {
    "terminalfeed": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://terminalfeed.io/api/mcp",
        "--header", "Authorization: Bearer tf_live_<64-char-hex>"
      ]
    }
  }
}

HTTP-native MCP clients (or curl):

curl -X POST https://terminalfeed.io/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tf_live_<64-char-hex>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"tf_premium_macro","arguments":{}}}'

Each tool call returns the same JSON payload as the underlying REST endpoint, plus an MCP _meta.credits_remaining field so the agent can monitor budget. Premium tools charge through the same atomic-charge contract as the REST endpoints.

Function-Calling Tool Definitions (Free)

Building an agent with OpenAI function-calling, Anthropic tool-use, or any LLM tool-call layer? Skip writing the tool definitions yourself. GET /api/llm-tools returns ready-to-paste tool definitions for every TerminalFeed endpoint (free + premium) in either format.

# Anthropic format
import requests, anthropic
tools = requests.get("https://terminalfeed.io/api/llm-tools?format=anthropic").json()["anthropic"]

client = anthropic.Anthropic()
resp = client.messages.create(
    model="claude-opus-4-7",
    tools=tools,                              # ready to use, no manual schema writing
    messages=[{"role": "user", "content": "What is the current Fed funds rate?"}],
    max_tokens=1024,
)

Optional ?tier=free or ?tier=premium filters. ?format=openai, ?format=anthropic, ?format=raw, or ?format=both (default). The endpoint costs no credits; the listed tools have their own pricing.

SDK

The official Python client is on PyPI: pip install terminalfeed. It is a single dependency-light module (only requests) covering the free tier, the full premium tier, and the USDC payment loop.

from terminalfeed import TerminalFeed

tf = TerminalFeed()
quote = tf.buy_credits(amount_usd=1.00)            # $1 = 50 credits
# Send USDC on Base to quote["wallet"] with memo quote["memo"]
tf.confirm_payment(tx_hash="0x...", nonce=quote["memo"])

print(tf.macro(history="30d"))                     # 2 credits
print(tf.crypto_deep(coins=["btc", "eth"]))        # 2 credits
print(tf.briefing(include=["btc", "predictions"])) # 1 credit
print("balance:", tf.balance())

Prefer vendoring over a dependency? The same module is one copy-paste file at sdk-python/terminalfeed.py.

Bearer tokens minted by the TensorFeed payment Worker work on TerminalFeed too (shared credit pool), so any agent that has pip install tensorfeed already has a token that authenticates here. With or without the SDK, a plain requests.get(..., headers={"Authorization": f"Bearer {token}"}) works. TypeScript and Rust wrappers welcome; share yours and we will link from this section.

FAQ

How do AI agents pay for API access without a human in the loop?

The agent buys credits with USDC on Base mainnet, gets a bearer token, and signs every premium request with Authorization: Bearer tf_live_<64-char-hex>. No KYC, no credit-card form, no signup flow. An autonomous agent that holds a wallet can complete the entire payment loop on its own: POST /api/payment/buy-credits, send the USDC, POST /api/payment/confirm, then call any /api/pro/* endpoint.

Can I use the same bearer token on TensorFeed.ai?

Yes. Credits and tokens are cross-redeemable across both sites. The TensorFeed payment Worker is the system of record for the credit balance, and both TerminalFeed and TensorFeed authenticate against it. One $1 USDC purchase, two data sources: real-time markets and infrastructure on TerminalFeed plus AI news and intelligence on TensorFeed.

What is the cheapest way to get aggregated real-time market data for an AI agent?

Per request, premium endpoints are 2 cents to 4 cents (1 to 2 credits at $1 = 50 credits). The closest paid alternatives (Messari, CoinAPI, Alpha Vantage paid tiers) start at $50 to $500 per month with KYC and monthly commits. The free DIY alternative is to manage 5 to 15 separate keys, each with its own auth flow, rate-limit pool, and key rotation burden.

Are premium API responses licensed as training data?

No. Premium responses are licensed for inference and reasoning use only. They are not licensed for use as training data, fine-tuning input, model distillation, or redistribution as a dataset. Free tier endpoints retain their existing permissive license. Full clauses live in Terms section 17.

What happens if an upstream source fails after my credit was charged?

Credits are decremented before the upstream fetch begins (the atomic-charge property). If one or more upstream sources fail, the response still returns a 200 with whatever data we successfully composed, and the credit still counts. The credit pays for the routing decision and the aggregation work, not a guaranteed upstream success. We cache aggressively (60 seconds for briefing and crypto-deep, 5 minutes for macro), so successive calls within the cache window cost no additional fetches.

How do I rotate a compromised bearer token?

Bearer tokens are first-class credentials. If yours leaks, treat it as lost: buy a new pack to mint a new token, then stop using the old one. The compromised token will continue to spend its remaining balance until depleted. Email [email protected] with the affected token if you suspect theft and want it deactivated faster.

Can I get a refund if I bought too many credits?

No. All credit purchases are final and non-refundable. The upside: credits never expire, so they remain spendable indefinitely on terminalfeed.io and tensorfeed.ai (shared credit pool). Buy in small amounts ($1 = 50 credits) until you know your call volume, then top up as needed.

Is there a free tier for testing the integration?

The full free TerminalFeed API requires no auth and is the right place to verify your HTTP plumbing before spending USDC. The free /api/briefing endpoint is structurally similar (composed payload) to the premium /api/pro/briefing, so you can dry-run your parsing logic against it. Premium adds Polymarket prediction markets, the optional include filter, and the optional 24-hour history series.

How do I verify the published wallet address is the real one?

The address is published at four locations that we cross-verify on every release: this page, /terms section 17.6, /llms.txt, and the public GitHub repository README. If any of the four show a different address, do not send funds and email [email protected] immediately. The intentional public redundancy is the trust mechanism.

Support

General questions: [email protected]. Billing or token issues: [email protected]. Status of upstream sources is on the free /api/service-status endpoint.