Skip to content

Commit 89a0144

Browse files
tinkle-communitytinkle-community
committed
docs: add README, examples, architecture docs, and LICENSE
1 parent e1947cb commit 89a0144

File tree

5 files changed

+223
-0
lines changed

5 files changed

+223
-0
lines changed

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
custom: ["https://claw402.ai"]

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 NoFxAiOS
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# claw402
2+
3+
[![PyPI version](https://img.shields.io/pypi/v/claw402.svg)](https://pypi.org/project/claw402/)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5+
6+
Typed Python SDK for [claw402.ai](https://claw402.ai) — pay-per-call crypto data APIs via [x402](https://www.x402.org/) micropayments.
7+
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.
9+
10+
## Install
11+
12+
```bash
13+
pip install claw402
14+
```
15+
16+
## Quick Start
17+
18+
```python
19+
from claw402 import Claw402
20+
21+
client = Claw402(private_key="0xYourPrivateKey")
22+
23+
# Fund flow — $0.001 per call
24+
flow = client.coinank.fund.realtime(product_type="SWAP")
25+
print(flow)
26+
27+
# AI trading signals
28+
signals = client.nofxos.netflow.top_ranking(limit=20, duration="1h")
29+
print(signals)
30+
31+
# Fear & Greed Index
32+
sentiment = client.coinank.indicator.fear_greed()
33+
print(sentiment)
34+
```
35+
36+
## Features
37+
38+
- **Typed methods** — every endpoint has a dedicated Python method with keyword arguments
39+
- **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)
41+
- **Context manager** — `with Claw402(...) as client:` for automatic cleanup
42+
- **Zero config** — just a private key, no API keys or registration
43+
- **Base mainnet** — pays $0.001 USDC per call on Coinbase L2
44+
45+
## API Overview
46+
47+
### Coinank (Market Data)
48+
49+
| Resource | Methods | Description |
50+
|----------|---------|-------------|
51+
| `coinank.fund` | `realtime`, `history` | Real-time & historical fund flow |
52+
| `coinank.oi` | `all`, `agg_chart`, `symbol_chart`, `kline`, ... | Open interest data |
53+
| `coinank.liquidation` | `orders`, `intervals`, `agg_history`, `liq_map`, `heat_map`, ... | Liquidation tracking |
54+
| `coinank.funding_rate` | `current`, `accumulated`, `hist`, `weighted`, `heatmap`, ... | Funding rate analytics |
55+
| `coinank.longshort` | `realtime`, `buy_sell`, `person`, `position`, ... | Long/short ratios |
56+
| `coinank.hyper` | `top_position`, `top_action` | HyperLiquid whale tracking |
57+
| `coinank.etf` | `us_btc`, `us_eth`, `us_btc_inflow`, `us_eth_inflow`, `hk_inflow` | ETF flow data |
58+
| `coinank.indicator` | `fear_greed`, `altcoin_season`, `btc_multiplier`, `ahr999`, ... | Market cycle indicators |
59+
| `coinank.market_order` | `cvd`, `agg_cvd`, `buy_sell_value`, ... | Taker flow / CVD |
60+
| `coinank.kline` | `lists` | OHLCV candlestick data |
61+
| `coinank.price` | `last` | Real-time price |
62+
| `coinank.rank` | `screener`, `oi`, `volume`, `price`, `liquidation`, ... | Rankings & screeners |
63+
| `coinank.news` | `list`, `detail` | Crypto news & alerts |
64+
65+
### Nofxos (AI Signals)
66+
67+
| Resource | Methods | Description |
68+
|----------|---------|-------------|
69+
| `nofxos.ai500` | `list`, `stats` | AI500 high-potential coin signals |
70+
| `nofxos.ai300` | `list`, `stats` | AI300 quant model rankings |
71+
| `nofxos.netflow` | `top_ranking`, `low_ranking` | Net capital flow rankings |
72+
| `nofxos.oi` | `top_ranking`, `low_ranking` | OI change rankings |
73+
| `nofxos.funding_rate` | `top`, `low` | Extreme funding rate coins |
74+
| `nofxos.price` | `ranking` | Price change rankings |
75+
| `nofxos.upbit` | `hot`, `netflow_top_ranking`, `netflow_low_ranking` | Korean market data |
76+
77+
## Configuration
78+
79+
```python
80+
# Custom base URL
81+
client = Claw402(
82+
private_key="0x...",
83+
base_url="https://custom.gateway",
84+
)
85+
```
86+
87+
## How Payment Works
88+
89+
1. SDK sends a GET request to the endpoint
90+
2. Server responds with `402 Payment Required` + payment details in header
91+
3. SDK signs an EIP-3009 `TransferWithAuthorization` for USDC on Base
92+
4. SDK retries the request with the `PAYMENT-SIGNATURE` header
93+
5. Server verifies payment on-chain and returns the data
94+
95+
Your private key **never leaves your machine** — it only signs the payment locally.
96+
97+
## Requirements
98+
99+
- Python 3.9+
100+
- A wallet with USDC on [Base mainnet](https://base.org)
101+
- Get USDC on Base: [bridge.base.org](https://bridge.base.org)
102+
103+
## License
104+
105+
MIT

‎docs/ARCHITECTURE.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
```
6+
claw402 (pip)
7+
├── claw402/
8+
│ ├── __init__.py ← Package entry + re-exports
9+
│ ├── client.py ← Core client: x402 V2 payment flow
10+
│ ├── errors.py ← Error types
11+
│ └── generated/ ← Auto-generated from providers/*.yaml
12+
│ ├── coinank.py ← 78 endpoints: market data, ETF, liquidations, etc.
13+
│ └── nofxos.py ← 18 endpoints: AI signals, rankings, Upbit
14+
└── examples/
15+
└── basic.py ← Usage example
16+
```
17+
18+
## Payment Flow (x402 V2)
19+
20+
```
21+
Client claw402.ai Base L2
22+
│ │ │
23+
│─── GET /api/v1/... ──────────▶│ │
24+
│◀── 402 + Payment-Required ────│ │
25+
│ │ │
26+
│ [sign EIP-3009 locally] │ │
27+
│ │ │
28+
│─── GET + PAYMENT-SIGNATURE ──▶│ │
29+
│ │── verify + settle ────────▶│
30+
│ │◀── tx confirmed ──────────│
31+
│◀── 200 + data ────────────────│ │
32+
```
33+
34+
## Code Generation
35+
36+
The `generated/` directory is produced by `sdks/codegen/` which reads
37+
`providers/*.yaml` (the same YAML files that configure the Go gateway)
38+
and emits typed SDK methods for TypeScript, Python, and Go.
39+
40+
Each YAML route becomes a typed method:
41+
42+
```yaml
43+
# providers/coinank.yaml
44+
- gateway_path: /api/v1/coinank/fund/realtime
45+
category: Fund
46+
allowed_params: [sortBy, productType, page, size]
47+
```
48+
49+
Becomes:
50+
51+
```python
52+
# generated/coinank.py
53+
def realtime(self, sort_by=None, product_type=None, page=None, size=None):
54+
return self._client._get('/api/v1/coinank/fund/realtime', params={
55+
'sortBy': sort_by, 'productType': product_type, ...
56+
})
57+
```

‎examples/basic.py‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
"""
2+
Basic usage of the claw402 Python SDK.
3+
4+
Usage:
5+
WALLET_PRIVATE_KEY=0x... python examples/basic.py
6+
"""
7+
8+
import os
9+
from claw402 import Claw402
10+
11+
key = os.environ["WALLET_PRIVATE_KEY"]
12+
13+
with Claw402(private_key=key) as client:
14+
# 1. Fear & Greed Index (no params)
15+
print("=== Fear & Greed Index ===")
16+
sentiment = client.coinank.indicator.fear_greed()
17+
print(sentiment)
18+
19+
# 2. Fund flow with params
20+
print("\n=== Fund Flow (SWAP, top 5) ===")
21+
flow = client.coinank.fund.realtime(product_type="SWAP", size=5)
22+
print(flow)
23+
24+
# 3. AI500 signals
25+
print("\n=== AI500 Top Signals ===")
26+
ai500 = client.nofxos.ai500.list(limit=10)
27+
print(ai500)
28+
29+
# 4. Net capital inflow ranking
30+
print("\n=== Net Inflow Top 10 (1h) ===")
31+
inflow = client.nofxos.netflow.top_ranking(limit=10, duration="1h")
32+
print(inflow)
33+
34+
# 5. BTC price
35+
print("\n=== BTC Latest Price ===")
36+
price = client.coinank.price.last(
37+
symbol="BTCUSDT", exchange="Binance", product_type="SWAP"
38+
)
39+
print(price)

0 commit comments

Comments
 (0)