142 lines
3 KiB
Markdown
142 lines
3 KiB
Markdown
# Cardano Chain Data API
|
|
|
|
REST API for querying Cardano blockchain data via db-sync PostgreSQL database.
|
|
|
|
## Stack
|
|
|
|
- **FastAPI** — async Python API framework
|
|
- **asyncpg** — async PostgreSQL driver
|
|
- **Redis** — rate limiting + response caching
|
|
|
|
## Deployment
|
|
|
|
```bash
|
|
cd /opt/cardano/dbsync
|
|
sudo docker compose up -d --build
|
|
```
|
|
|
|
API runs on `127.0.0.1:8765` (localhost only, VPN access via future rebind to `192.168.254.105:8765`).
|
|
|
|
## Authentication
|
|
|
|
### Rate Limits
|
|
- Anonymous (no key): 20 req/min per IP
|
|
- Standard API key: 100 req/min
|
|
- Elevated API key: 1000 req/min
|
|
- Master key: unlimited
|
|
|
|
### Using API Keys
|
|
```bash
|
|
# Header (preferred)
|
|
curl -H "X-API-Key: capi_xxx" http://127.0.0.1:8765/v1/block/latest
|
|
|
|
# Query param
|
|
curl http://127.0.0.1:8765/v1/block/latest?api_key=capi_xxx
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
### Sync Status
|
|
```
|
|
GET /v1/sync/status
|
|
```
|
|
|
|
### Blocks
|
|
```
|
|
GET /v1/block/latest
|
|
GET /v1/block/{block_no}
|
|
```
|
|
|
|
### Addresses
|
|
```
|
|
GET /v1/address/{address}/balance
|
|
GET /v1/address/{address}/tokens
|
|
GET /v1/address/{address}/transactions?page=1&limit=20&order=desc
|
|
```
|
|
|
|
### Transactions
|
|
```
|
|
GET /v1/tx/{tx_hash}
|
|
```
|
|
|
|
### Assets
|
|
```
|
|
GET /v1/asset/{policy_id}/info
|
|
GET /v1/asset/{policy_id}/{asset_name}/holders?limit=20
|
|
```
|
|
|
|
### Pools
|
|
```
|
|
GET /v1/pool/{pool_id}/info
|
|
```
|
|
|
|
### Admin (master key required)
|
|
```
|
|
POST /admin/keys — create API key
|
|
DELETE /admin/keys/{key} — revoke key
|
|
GET /admin/keys — list all keys
|
|
GET /admin/stats — usage stats
|
|
```
|
|
|
|
## Known Policy IDs
|
|
|
|
- **TRP**: `9c4bd4a90cdb73d9ff681215ecf7dea9fb183d916d30487d17098e05`
|
|
- **MAP**: `24bd9e7b9ae3a61df79eca72fd8355d0f7767e4c55a04a0d919c019c`
|
|
|
|
## Future: TRP Token Gating
|
|
|
|
Design for decentralized, permissionless API access based on TRP token holdings:
|
|
|
|
### Tier Mapping
|
|
- 0 TRP → anonymous rate limits (20 req/min)
|
|
- 50+ TRP → standard tier (100 req/min)
|
|
- 500+ TRP → elevated tier (1000 req/min)
|
|
|
|
### Implementation Plan
|
|
1. `POST /admin/keys/verify-trp` endpoint
|
|
2. Takes Cardano address, queries `/v1/address/{addr}/tokens`
|
|
3. Checks TRP policy balance
|
|
4. Auto-creates or upgrades API key based on holdings
|
|
5. Stores `owner` (address) and `trp_balance` in key hash
|
|
|
|
### Data Model (already in place)
|
|
API keys stored in Redis as:
|
|
```
|
|
apikey:<key> → {
|
|
tier: "standard"|"elevated",
|
|
label: "...",
|
|
owner: "addr1...", # Cardano address
|
|
trp_balance: 500, # Last verified TRP balance
|
|
created_at: "..."
|
|
}
|
|
```
|
|
|
|
### Benefits
|
|
- **Permissionless**: Anyone can verify holdings and get access
|
|
- **Decentralized**: No manual approval needed
|
|
- **Incentivized**: Holding TRP = better API access
|
|
- **Revocable**: Re-verify periodically to maintain tier
|
|
|
|
## Caching
|
|
|
|
Response TTLs:
|
|
- Balance/tokens: 60s
|
|
- Transactions: 30s
|
|
- Latest block: 10s
|
|
- TX details: 300s (immutable)
|
|
- Asset info: 120s
|
|
- Pool info: 120s
|
|
- Sync status: 5s
|
|
|
|
## Environment Variables
|
|
|
|
```
|
|
DB_HOST=postgres-dbsync
|
|
DB_PORT=5432
|
|
DB_NAME=cexplorer
|
|
DB_USER=dbsync
|
|
DB_PASS=...
|
|
REDIS_HOST=redis-api
|
|
REDIS_PORT=6379
|
|
API_MASTER_KEY=capi_...
|
|
```
|