Quick Reference
Everything a developer needs in one place. Keep this open while building.
API
| Value | |
|---|---|
| Base URL | https://{tenant}-platform.chainara.io/api/v2 |
| Auth header | X-API-Key: ek_YOUR_KEY |
| Content-Type | application/json |
Replace {tenant}-platform with your subdomain (e.g. ripple-platform). The default Chainara instance uses platform.chainara.io.
Rate limits
| Limiter | Window | Limit |
|---|---|---|
| Enterprise (per-minute) | 1 min | 500 requests |
| Enterprise (burst) | 2 hrs | 10,000 requests |
| Public endpoints | 15 min | 1,000 requests |
| Bulk operations | 1 hr | 100 requests |
| Auth endpoints | 15 min | 10 requests |
Monthly limit: 100,000 requests per API key.
Returns 429 with Retry-After header when exceeded.
Blockchain IDs
Used in any endpoint with a blockchainId path parameter.
| ID | Chain | Symbol | Network Type | Status |
|---|---|---|---|---|
1 | XRPL | XRP | xrpl | Available |
2 | Stellar | XLM | stellar | Available |
3 | RLUSD | RLUSD | xrpl | Available |
4 | Flare | FLR | evm | Available |
5 | Bitcoin | BTC | bitcoin | Available |
6 | Ethereum | ETH | evm | Available |
7 | BSC | BNB | evm | Experimental |
8 | Polygon | MATIC | evm | Experimental |
9 | Arbitrum | ARB | evm | Experimental |
10 | Avalanche | AVAX | evm | Experimental |
11 | SUI | SUI | sui | Experimental |
Key endpoints
| Endpoint | Description |
|---|---|
GET /wallets/{blockchainId}/{address} | Full wallet intelligence |
GET /wallets/{blockchainId}/{address}/risk-score | Risk score only (faster) |
GET /fraud-reports | List fraud reports |
POST /fraud-reports | Submit a fraud report |
GET /blacklist | Blacklisted addresses |
GET /feed/snapshot | Full threat feed snapshot |
POST /webhooks | Register a webhook endpoint |
POST /ingest/reports | Bulk-ingest fraud reports |
POST /ingest/wallets | Bulk-ingest wallet flags |
POST /ingest/domains | Bulk-ingest domains |
GET /health | API health check |
Risk score ranges
| Score | Label | Recommended action |
|---|---|---|
| 0–24 | Safe | No action |
| 25–49 | Low Risk | Add to watchlist |
| 50–74 | Medium Risk | Flag for review |
| 75–89 | High Risk | Block / submit report |
| 90–99 | Critical | Immediate block + escalate |
Scores ≥ 75 trigger automatic alerts. Scores ≥ 90 are auto-flagged as Critical.
Wallet severity tiers
| Tier | Meaning | Action |
|---|---|---|
blacklisted | Confirmed malicious: corroborated by Ripple, Xaman, or investigations | Block transactions |
suspicious | Flagged by feeds, community reports, or on-chain patterns | Monitor / risk score |
Webhook events
| Event | When it fires |
|---|---|
indicator_added | New threat verified and added |
indicator_updated | Existing indicator updated with new evidence |
indicator_removed | Indicator removed (false positive or domain taken down) |
Signature header: X-Chainara-Signature: sha256=<hmac-hex>
Secret algorithm: HMAC-SHA256 over raw request body.
Threat feed indicator types
type | Description |
|---|---|
domain | Malicious or suspicious domain |
wallet | Blockchain address (see severity tier) |
domain_wallet_pair | Verified domain → drain wallet link |
fraud_report | Full investigation report |
community_report | Victim-submitted scam report |
Threat types
| Type | Description |
|---|---|
xrp_scam | XRP/Ripple-themed scam |
executive_impersonation | Impersonates a public figure |
giveaway_scam | Fake airdrop or doubling scheme |
phishing | Credential theft |
investment_fraud | Fake investment / Ponzi |
political_scam | Uses political figures as lure |
scam_recipient | Wallet that received victim funds |
drain_wallet | Wallet used to drain scam site |
exfil_pattern | On-chain fund exfiltration pattern |
Fraud / report types
| Type | Description |
|---|---|
scam_website | Fraudulent website |
fake_giveaway | Fake airdrop or doubling event |
fraudulent_wallet | Confirmed bad wallet |
suspicious_domain | Suspicious but unconfirmed domain |
social_media_scam | Scam operated via social channels |
For the full taxonomy see Threat Categories.
Ingest rules
- All ingest submissions tagged
source_tier: community,verification_status: pending - Risk scores capped at 65 until analyst verifies
- Admins review via Admin → Fraud Reports → External Intel
Incremental sync pattern
# Store generated_at from last response; pass as ?since= on next call
params = {"since": load_last_sync_timestamp()}
r = requests.get(f"{BASE_URL}/feed/snapshot", headers=headers, params=params)
save_last_sync_timestamp(r.json()["generated_at"])
Pagination cursors expire after 1 hour. If expired, restart with a fresh snapshot.
Error codes
| Code | Meaning |
|---|---|
400 | Bad request: invalid parameters |
401 | Missing or invalid API key |
403 | Valid key but insufficient plan/permissions |
404 | Resource not found |
429 | Rate limited: check Retry-After header |
500 | Server error: retry with exponential backoff |