>_ 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.

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

24-hour window from credit purchase. Email [email protected] with your tx hash and we refund the unused balance in USDC on Base, less network fees. After 24 hours, credits are non-refundable but never expire, so they remain spendable.

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.

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

No PyPI release in v1. 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 format that authenticates here. Pass it in requests.get(..., headers={"Authorization": f"Bearer {token}"}) and you are done.

For agents that prefer typed methods, a single-file Python reference client lives in the public repo at sdk-python/terminalfeed_client.py. Copy it into your codebase. It depends only on requests.

from terminalfeed_client 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())

When the integration sees real traffic, this file is the seed for either an extension to the tensorfeed PyPI package or a standalone terminalfeed package. 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?

Yes within 24 hours of purchase. Email [email protected] with the on-chain transaction hash and we refund the unused balance in USDC on Base, less network fees. After 24 hours credits are non-refundable, but they never expire and remain spendable indefinitely.

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, refunds, or token issues: [email protected]. Status of upstream sources is on the free /api/service-status endpoint.