Metadata-Version: 2.4
Name: terminalfeed
Version: 0.1.0
Summary: Python client for the TerminalFeed real-time data API: live markets, crypto, macro, and world data for humans and AI agents
Author-email: Ripper <hello@terminalfeed.io>
License-Expression: MIT
Project-URL: Homepage, https://terminalfeed.io
Project-URL: Documentation, https://terminalfeed.io/developers/agent-payments
Project-URL: API Catalog, https://terminalfeed.io/api/meta/pro
Project-URL: Source, https://github.com/RipperMercs/terminalfeed/tree/master/sdk-python
Keywords: terminalfeed,market-data,crypto,bitcoin,macro,real-time,ai-agents,mcp,api-client,usdc,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: license-file

# terminalfeed

Python client for the [TerminalFeed](https://terminalfeed.io) real-time data API: live markets, crypto, macro, and world data, built for humans on a second monitor and for AI agents that pay their own way.

```
pip install terminalfeed
```

Single module, one dependency (`requests`). You can also vendor it: copy [`terminalfeed.py`](https://github.com/RipperMercs/terminalfeed/blob/master/sdk-python/terminalfeed.py) straight into your codebase.

## Free tier (no token, no signup)

```python
from terminalfeed import TerminalFeed

tf = TerminalFeed()

print(tf.free_btc_price())        # live BTC price
print(tf.free_briefing())         # one-call world snapshot
print(tf.free_feed_reliability()) # ranked reliability of every feed
print(tf.regime_preview())        # free taste of the market-regime verdict
print(tf.pro_catalog())           # machine-readable premium catalog with prices
```

There are 30+ free endpoints in total (stocks, earthquakes, prediction markets, space launches, gas prices, and more). The full list lives at [terminalfeed.io/for-devs/api](https://terminalfeed.io/for-devs/api) and in [`llms.txt`](https://terminalfeed.io/llms.txt).

## Premium tier (USDC on Base, no KYC)

1 credit = $0.02, and $1 USDC buys 50 credits. The entire payment loop is agent-completable: no signup form, no credit card, no human in the loop.

```python
from terminalfeed import TerminalFeed

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

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

## Token sharing with TensorFeed

Bearer tokens (`tf_live_<64-char-hex>`) are cross-redeemable with [TensorFeed](https://tensorfeed.ai) (`pip install tensorfeed`). A token minted on either site authenticates on both, against a shared credit pool. One purchase, two data sources.

## Error handling

```python
from terminalfeed import TerminalFeed, PaymentRequiredError, TerminalFeedError

try:
    tf.macro()
except PaymentRequiredError as e:
    # e.reason is one of: missing_token, invalid_token,
    # insufficient_credits, expired, billing_unavailable
    print("need credits:", e.reason, e.signup_url)
except TerminalFeedError as e:
    print("API error:", e)
```

## Links

- Docs: <https://terminalfeed.io/developers/agent-payments>
- Developer hub: <https://terminalfeed.io/for-devs>
- OpenAPI spec: <https://terminalfeed.io/openapi.json>
- MCP server config: <https://terminalfeed.io/for-devs/mcp>

MIT licensed.
