BTC -
API/ AGENT PAYMENTSPREMIUMUSDC ON BASEBEARER AUTHNO SUBSCRIPTION

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.

Proven on mainnet. April 27, 2026: 1 USDC sent to the published wallet on Base, credits minted, bearer token issued, and a premium endpoint called successfully on the first try. Tx hash 0x13bc9e2378edae44685a63bdedd3ba802372e2e656961610b8c169ca60431c0e. Walkthrough: We Validated Agent Payments End-to-End on Base Mainnet. The same wallet and the same credit pool serve TerminalFeed.
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/.

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
GET/api/pro/briefing1 credit

One-call world briefing composed from recent earthquakes, top Hacker News story count, ISS crew, upcoming space launches, and live Polymarket prediction markets sorted by 24h volume.

Optional params: ?include=btc,fear-greed,predictions filters which sections appear. ?history=24h adds an hourly BTC price series.

GET/api/pro/macro2 credits

Macro snapshot: FRED economic indicators (Fed funds rate, CPI, unemployment, GDP growth, 10-year treasury), forex rates from Frankfurter (EUR, JPY, GBP, CHF against USD), and commodities (WTI oil, Henry Hub natural gas) from FRED. All sources are public/gov (FRED) or ECB reference rates (Frankfurter).

Optional params: ?history=30d adds 30 daily observations for FRED series and a daily forex time-series.

GET/api/pro/world-deltas2 credits

Time-sorted event stream for monitor agents that poll periodically. Aggregates events from four upstream sources into one feed: USGS earthquakes M4.0+, Hacker News current front-page items (within the since window), recently updated Polymarket markets with $10K+ 24h volume, and space launches in a [-1h, +12h] window. Each event has type, timestamp, severity, and structured data.

Optional params: ?since=<ISO 8601 timestamp> returns only events newer than this. Defaults to 1 hour ago. Clamped to 1 hour ago if older (the rolling-cache horizon). Pass your last poll timestamp on each call.

Why this exists: a monitor agent today has to poll USGS, HN, Polymarket, and TheSpaceDevs separately and reconcile timestamps client-side. This endpoint does the merge server-side. 1-hour rolling cache means sub-second response when warm.

GET/api/pro/agent-context2 credits

The "always start here" call. Composes multiple public/gov upstream sources into a curated world-state snapshot: Fed funds rate, USD-base forex (EUR/JPY/GBP/CHF), HN front page top 5, significant earthquakes 24h, upcoming space launches, top 3 Polymarket markets by volume, and infrastructure status (GitHub, Cloudflare, OpenAI, Anthropic).

The killer feature: returns BOTH a structured JSON context object for parsers AND a pre-formatted system_prompt string the agent pastes verbatim into its LLM context window. Saves the agent from making many separate calls AND from writing the formatter.

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": "..."}]
)

What you can't easily build yourself: the data is free elsewhere; the curation (which signals matter, how to compress them into a coherent narrative) is what an agent pays for.

GET/api/pro/correlation-matrix2 credits

Pre-computed 30-day macro Pearson correlation matrix on daily simple returns. Four FRED series (US gov, public domain) across three classes: commodity (WTI oil), rates (10Y and 2Y treasury yields), and fx (trade-weighted USD index).

Returns both a pairs array (sorted by absolute r descending, with relationship and direction labels) and an NxN matrix object for direct lookup like m.matrix.BTC.ETH.

Why this exists: a portfolio agent today has to fetch several historical macro series, normalize them to daily returns, and run a covariance computation per cycle. This endpoint precomputes it server-side. Cached 30 minutes since correlations move slowly within a day.

GET/api/pro/github-velocity2 credits

Composed GitHub developer-attention snapshot for dev-tool agents, AI/ML researchers, and infrastructure-tracking agents. Top 30 repos created in the last 7 days sorted by stars (with stars-per-day, language, topics, license, owner type, AI/ML focus flag), top 15 AI/ML-focused active repos (topic:llm with commits in last 30 days), language and topic aggregates, and the AI/ML share-of-trending percentage.

Source: GitHub Search API. Free without auth (60 req/hour); we cache 30 minutes so even unauthenticated upstream is well under rate limit. Optional GITHUB_TOKEN Worker secret bumps to 5000 req/hour.

Why this exists: tracks where developer attention is concentrating right now. Live test showed 50% of trending-7d repos are AI/ML focused, with Python dominating (11 of 30 repos, ~7K stars).

PRICING
ItemDetail
Rate$1 USDC = 50 credits
ChainBase mainnet
Briefing1 credit per call
Macro2 credits per call
Agent context2 credits per call
SubscriptionNone. Pay only for what you call.
ExpiryNone. Credits never expire.
Bulk discountNot available in v1. Larger purchases coming.

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 support@terminalfeed.io.

0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1
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)

ReasonMeaning
missing_tokenNo Authorization header was sent.
invalid_tokenToken format is wrong or token does not exist.
insufficient_creditsToken is valid but balance is too low for this endpoint.
billing_unavailableAuth service unreachable. Retry; if persistent, contact support.
expiredToken revoked. Buy a new pack.
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)
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. The free tier endpoints retain their existing permissive license. See /terms for the full clauses.
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.briefing(include=["predictions"]))        # 1 credit
print("balance:", tf.balance())

Prefer vendoring over a dependency? The module is a single file; grab it from the published package at pypi.org/project/terminalfeed and copy terminalfeed.py out of it.

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, 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 support@terminalfeed.io 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 three locations that we cross-verify on every release: this page, /terms section 17.6, and /llms.txt. If any of the three show a different address, do not send funds and email support@terminalfeed.io immediately. The intentional public redundancy is the trust mechanism.

SUPPORT