Skip to content

Commit a2a62f4

Browse files
feat: add 7 new providers, fix codegen for all edge cases
- Add Alpaca, Alpha Vantage, Polygon, Tushare, Twelvedata, OpenAI, Anthropic - Add _post() method for JSON POST endpoints (AI providers) - Fix Python keyword params: from→from_, to→to_, type→type_ etc. - Fix sub-resource/method name collision (get_bars, get_time_series) - Sub-resources: alphavantage.us, tushare.cn, twelvedata.indicator/metals/indices - Update README with correct API surface for all 9 providers - Update test_sdk.py to test all 9 providers with correct API calls
1 parent aad0c44 commit a2a62f4

12 files changed

Lines changed: 994 additions & 111 deletions

File tree

README.md

Lines changed: 186 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
[![PyPI version](https://img.shields.io/pypi/v/claw402.svg)](https://pypi.org/project/claw402/)
44
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
55

6-
Typed Python SDK for [claw402.ai](https://claw402.ai) — pay-per-call crypto data APIs via [x402](https://www.x402.org/) micropayments.
6+
Typed Python SDK for [claw402.ai](https://claw402.ai) — pay-per-call data APIs via [x402](https://www.x402.org/) micropayments.
77

8-
**96+ endpoints** covering fund flow, liquidations, ETF flows, AI trading signals, whale tracking, funding rates, open interest, and more. No API key, no signup, no subscription — just a Base wallet with USDC.
8+
**200+ endpoints** covering crypto market data, US stocks, China A-shares, forex, global time-series, and AI (OpenAI/Anthropic). No API key, no signup, no subscription — just a Base wallet with USDC.
99

1010
## Install
1111

@@ -20,31 +20,49 @@ from claw402 import Claw402
2020

2121
client = Claw402(private_key="0xYourPrivateKey")
2222

23-
# Fund flow — $0.001 per call
23+
# Crypto: Fund flow — $0.001/call
2424
flow = client.coinank.fund.realtime(product_type="SWAP")
2525
print(flow)
2626

27-
# AI trading signals
28-
signals = client.nofxos.netflow.top_ranking(limit=20, duration="1h")
29-
print(signals)
27+
# US Stocks: Latest quote — $0.001/call
28+
quote = client.alpaca.quotes.latest(symbols="AAPL,TSLA")
29+
print(quote)
3030

31-
# Fear & Greed Index
32-
sentiment = client.coinank.indicator.fear_greed()
33-
print(sentiment)
31+
# US Stocks: Market snapshot — $0.002/call
32+
snap = client.polygon.snapshot.all(tickers="AAPL")
33+
print(snap)
34+
35+
# China A-shares — $0.001/call
36+
stocks = client.tushare.cn.stock_basic(list_status="L")
37+
print(stocks)
38+
39+
# Forex time-series — $0.001/call
40+
ts = client.twelvedata.get_time_series(symbol="EUR/USD", interval="1h")
41+
print(ts)
42+
43+
# AI: OpenAI chat — $0.01/call
44+
resp = client.openai.openai.chat({"messages": [{"role": "user", "content": "Hello"}]})
45+
print(resp)
46+
47+
# AI: Anthropic Claude — $0.015/call
48+
resp = client.anthropic.anthropic.messages({"messages": [{"role": "user", "content": "Hello"}]})
49+
print(resp)
3450
```
3551

3652
## Features
3753

3854
- **Typed methods** — every endpoint has a dedicated Python method with keyword arguments
3955
- **Automatic x402 payment** — signs EIP-3009 USDC transfers locally, never sends your key
40-
- **Two resource groups**`client.coinank.*` (market data) and `client.nofxos.*` (AI signals)
56+
- **9 provider groups**crypto, US stocks, China stocks, forex, global data, and AI
4157
- **Context manager**`with Claw402(...) as client:` for automatic cleanup
4258
- **Zero config** — just a private key, no API keys or registration
43-
- **Base mainnet** — pays $0.001 USDC per call on Coinbase L2
59+
- **Base mainnet** — pays USDC per call on Coinbase L2
4460

4561
## API Overview
4662

47-
### Coinank (Market Data)
63+
### Crypto Market Data
64+
65+
#### Coinank
4866

4967
| Resource | Methods | Description |
5068
|----------|---------|-------------|
@@ -62,7 +80,7 @@ print(sentiment)
6280
| `coinank.rank` | `screener`, `oi`, `volume`, `price`, `liquidation`, ... | Rankings & screeners |
6381
| `coinank.news` | `list`, `detail` | Crypto news & alerts |
6482

65-
### Nofxos (AI Signals)
83+
#### Nofxos (AI Signals)
6684

6785
| Resource | Methods | Description |
6886
|----------|---------|-------------|
@@ -74,6 +92,160 @@ print(sentiment)
7492
| `nofxos.price` | `ranking` | Price change rankings |
7593
| `nofxos.upbit` | `hot`, `netflow_top_ranking`, `netflow_low_ranking` | Korean market data |
7694

95+
### US Stock & Options Market
96+
97+
#### Alpaca
98+
99+
| Resource | Methods | Description |
100+
|----------|---------|-------------|
101+
| `alpaca.quotes` | `latest`, `history` | Real-time & historical quotes — $0.001–0.002/call |
102+
| `alpaca.bars` | `latest` | Latest OHLCV bar — $0.001/call |
103+
| `alpaca.trades` | `latest`, `history` | Real-time & historical trades — $0.001–0.002/call |
104+
| `alpaca.options` | `bars`, `quotes_latest`, `snapshots` | Options chain data — $0.003/call |
105+
| `alpaca` | `get_bars`, `snapshots`, `snapshot`, `movers`, `most_actives`, `news`, `corporate_actions` | Direct market endpoints — $0.001–0.002/call |
106+
107+
```python
108+
# Latest quotes for multiple symbols
109+
q = client.alpaca.quotes.latest(symbols="AAPL,MSFT,TSLA")
110+
111+
# Historical bars
112+
bars = client.alpaca.get_bars(symbols="AAPL", timeframe="1Day", start="2024-01-01")
113+
114+
# Top market movers
115+
movers = client.alpaca.movers(top=10, market_type="stocks")
116+
117+
# Options snapshots
118+
opts = client.alpaca.options.snapshots(symbols="AAPL240119C00150000")
119+
```
120+
121+
#### Polygon
122+
123+
| Resource | Methods | Description |
124+
|----------|---------|-------------|
125+
| `polygon.aggs` | `aggs`, `grouped_daily`, `daily_open_close`, `previous_close` | Aggregates / OHLCV bars — $0.001/call |
126+
| `polygon.snapshots` | `all_tickers`, `single_ticker`, `gainers_losers`, `universal_snapshot`, `options_chain` | Full market snapshots — $0.002/call |
127+
| `polygon.trades` | `trades`, `last_trade`, `quotes`, `last_quote` | Trade & quote tick data — $0.002/call |
128+
| `polygon` | `ticker_details`, `market_status`, `ticker_types`, `exchanges`, `conditions`, `sma`, `ema`, `rsi`, `macd` | Reference & technical indicators — $0.001–0.003/call |
129+
130+
```python
131+
# OHLCV bars
132+
bars = client.polygon.aggs.aggs(
133+
stocksTicker="AAPL", multiplier=1, timespan="day",
134+
from_="2024-01-01", to="2024-12-31"
135+
)
136+
137+
# RSI indicator
138+
rsi = client.polygon.rsi(stocksTicker="AAPL", timespan="day", window=14)
139+
140+
# Options chain
141+
chain = client.polygon.snapshots.options_chain(underlyingAsset="AAPL")
142+
```
143+
144+
#### Alpha Vantage
145+
146+
| Resource | Methods | Description |
147+
|----------|---------|-------------|
148+
| `alphavantage.us` | `quote`, `search`, `daily`, `daily_adjusted`, `intraday`, `weekly`, `monthly`, `overview`, `earnings`, `income`, `balance_sheet`, `cash_flow`, `movers`, `news`, `rsi`, `macd`, `bbands`, `sma`, `ema` | Comprehensive financial data — $0.001–0.003/call |
149+
150+
```python
151+
# Real-time quote
152+
quote = client.alphavantage.us.quote(symbol="AAPL")
153+
154+
# Daily OHLCV
155+
daily = client.alphavantage.us.daily(symbol="AAPL", outputsize="compact")
156+
157+
# Top movers (no params)
158+
movers = client.alphavantage.us.movers()
159+
160+
# News sentiment
161+
news = client.alphavantage.us.news(tickers="AAPL")
162+
```
163+
164+
### China A-Shares
165+
166+
#### Tushare
167+
168+
| Resource | Methods | Description |
169+
|----------|---------|-------------|
170+
| `tushare.cn` | `stock_basic`, `daily`, `weekly`, `monthly`, `daily_basic`, `trade_cal`, `income`, `balance_sheet`, `cash_flow`, `dividend`, `northbound`, `moneyflow`, `margin`, `margin_detail`, `top_list`, `top_inst` | China A-share market data — $0.001–0.003/call |
171+
172+
```python
173+
# Stock list
174+
stocks = client.tushare.cn.stock_basic(list_status="L")
175+
176+
# Daily OHLCV
177+
daily = client.tushare.cn.daily(ts_code="000001.SZ", start_date="20240101", end_date="20240131")
178+
179+
# Money flow
180+
flow = client.tushare.cn.moneyflow(ts_code="000001.SZ", start_date="20240101")
181+
182+
# Northbound capital
183+
north = client.tushare.cn.northbound(trade_date="20240101")
184+
```
185+
186+
### Global Time-Series & Forex
187+
188+
#### Twelve Data
189+
190+
| Resource | Methods | Description |
191+
|----------|---------|-------------|
192+
| `twelvedata.time_series` | `complex` (POST) | Complex multi-symbol/indicator query — $0.005/call |
193+
| `twelvedata.indicator` | `sma`, `ema`, `rsi`, `macd`, `bbands`, `atr` | Technical indicators — $0.002/call |
194+
| `twelvedata.metals` | `price`, `time_series` | Precious metals prices — $0.001/call |
195+
| `twelvedata.indices` | `list_`, `quote` | Global index data — $0.001/call |
196+
| `twelvedata` | `get_time_series`, `price`, `quote`, `eod`, `exchange_rate`, `forex_pairs`, `economic_calendar` | Direct endpoints — $0.001/call |
197+
198+
```python
199+
# Time series (use get_time_series, NOT time_series — time_series is the sub-resource)
200+
ts = client.twelvedata.get_time_series(symbol="EUR/USD", interval="1h", outputsize=3)
201+
202+
# Technical indicators
203+
rsi = client.twelvedata.indicator.rsi(symbol="AAPL", interval="1day", time_period=14, outputsize=3)
204+
205+
# Real-time price
206+
price = client.twelvedata.price(symbol="BTC/USD")
207+
208+
# Metals
209+
gold = client.twelvedata.metals.price(symbol="XAU/USD")
210+
```
211+
212+
### AI Providers
213+
214+
#### OpenAI
215+
216+
| Resource | Methods | Description |
217+
|----------|---------|-------------|
218+
| `openai.openai` | `chat`, `chat_mini`, `embeddings`, `embeddings_large`, `images`, `models` | OpenAI API — $0.001–0.05/call |
219+
220+
```python
221+
# Chat (GPT-4o)
222+
resp = client.openai.openai.chat({
223+
"model": "gpt-4o",
224+
"messages": [{"role": "user", "content": "Analyze AAPL stock trend"}]
225+
})
226+
227+
# Embeddings
228+
emb = client.openai.openai.embeddings({
229+
"input": "crypto market sentiment",
230+
"model": "text-embedding-3-small"
231+
})
232+
```
233+
234+
#### Anthropic
235+
236+
| Resource | Methods | Description |
237+
|----------|---------|-------------|
238+
| `anthropic.anthropic` | `messages`, `messages_extended`, `count_tokens` | Anthropic Claude API — $0.01–0.015/call |
239+
240+
```python
241+
# Claude messages
242+
resp = client.anthropic.anthropic.messages({
243+
"model": "claude-opus-4-6",
244+
"max_tokens": 1024,
245+
"messages": [{"role": "user", "content": "Summarize this earnings report: ..."}]
246+
})
247+
```
248+
77249
## Configuration
78250

79251
```python
@@ -86,7 +258,7 @@ client = Claw402(
86258

87259
## How Payment Works
88260

89-
1. SDK sends a GET request to the endpoint
261+
1. SDK sends a GET/POST request to the endpoint
90262
2. Server responds with `402 Payment Required` + payment details in header
91263
3. SDK signs an EIP-3009 `TransferWithAuthorization` for USDC on Base
92264
4. SDK retries the request with the `PAYMENT-SIGNATURE` header

0 commit comments

Comments
 (0)