# OmniRisk API — Full Reference for LLMs and AI Agents
> Version: v1 | Base URL: https://api.omnirisk.io | Auth: x-api-key header
> Website: https://omnirisk.io | Docs: https://omnirisk.io/developer/guide | Spec: https://omnirisk.io/openapi.json

This document is designed to be loaded as context by AI agents, coding assistants, and autonomous
tools. It contains every endpoint, parameter, example request, and example response for the
OmniRisk REST API.

---

## Table of Contents

1. Overview
2. Authentication
3. Rate Limits
4. Supported Chains
5. Error Reference
6. Endpoints — System
7. Endpoints — Developer (API Key Management)
8. Endpoints — Token
9. Endpoints — Market
10. Endpoints — Wallet
11. Agentic Usage Notes
12. Pagination

---

## 1. Overview

OmniRisk provides real-time crypto risk intelligence. The API surfaces:

- **Token risk scores** — 0-100 score plus a label (safe / caution / risky / critical)
- **Wallet analysis** — risk profile for any on-chain address
- **Market signals** — macro regime, heatmap, trending tokens
- **API key management** — create, rotate, revoke, and track usage

All responses are JSON. All timestamps are ISO 8601 UTC. Numeric scores are floats.

Base URL: `https://api.omnirisk.io`
Version prefix: `/v1/`
Docs: `https://omnirisk.io/developer`
OpenAPI spec: `https://omnirisk.io/openapi.json`

---

## 2. Authentication

All endpoints except `GET /v1/health` require the `x-api-key` request header.

```
x-api-key: ri_live_<id>.<64-hex-chars>
```

### Key format

Keys follow the pattern `ri_live_` + short opaque identifier + `.` + 64 lowercase hex characters.

Example (not a real key):
```
ri_live_k7mxq2.a3f8b1c2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1
```

### Security rules for AI agents

- Read the key from the environment variable `OMNIRISK_API_KEY` — never hardcode it.
- Never pass the key as a URL query parameter (it will appear in server and proxy logs).
- Never include the key in client-side JavaScript bundles served to browsers.
- Use one key per service or agent so you can revoke selectively.
- Rotate keys immediately if you detect a leak using `POST /v1/developer/api-keys/{keyId}/rotate`.

---

## 3. Rate Limits

| Tier  | Requests / min | Monthly included |
|-------|---------------|-----------------|
| Free  | 60            | 10,000          |
| Pro   | 600           | 500,000         |
| Pro+  | 6,000         | Unlimited        |

### Response headers (every response)

| Header                  | Description                                              |
|-------------------------|----------------------------------------------------------|
| X-RateLimit-Limit       | Maximum requests allowed in the current 60-second window |
| X-RateLimit-Remaining   | Requests remaining in the current window                 |
| X-RateLimit-Reset       | Unix timestamp (seconds) when the window resets          |
| Retry-After             | (429 only) Seconds to wait before retrying               |

### Handling 429 errors

When you receive HTTP 429:
1. Read `Retry-After` from the response headers.
2. Wait that many seconds before retrying.
3. Use exponential back-off if `Retry-After` is absent.

---

## 4. Supported Chains

| Chain ID | Network    | Address format  | Notes                        |
|----------|------------|-----------------|------------------------------|
| eth      | Ethereum   | 0x hex (EIP-55) | EVM mainnet                  |
| bsc      | BNB Chain  | 0x hex (EIP-55) | EVM mainnet                  |
| sol      | Solana     | base58          | Non-EVM — use base58 addresses |
| base     | Base       | 0x hex (EIP-55) | Coinbase L2 (EVM)            |
| arb      | Arbitrum   | 0x hex (EIP-55) | Arbitrum One (EVM)           |
| poly     | Polygon    | 0x hex (EIP-55) | Polygon PoS (EVM)            |
| avax     | Avalanche  | 0x hex (EIP-55) | Avalanche C-Chain (EVM)      |
| ftm      | Fantom     | 0x hex (EIP-55) | EVM mainnet                  |

Chain IDs are validated against a strict enum. Unknown chain IDs return `400 BAD_REQUEST` immediately.

### Address validation

All `address` parameters are validated at the API boundary against a format allowlist:

- **EVM chains**: `0x` + exactly 40 hex characters (`/^0x[0-9a-fA-F]{40}$/`)
- **Solana**: base58 string, 32–44 characters
- **Bittensor**: subnet netuid — numeric string, 1–4 digits

Addresses that do not match return `400 BAD_REQUEST`. Path-traversal characters and arbitrary strings are rejected at this layer before any downstream processing.


---

## 5. Error Reference

All errors return a consistent envelope:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "You have exceeded 60 requests per minute.",
    "docs_url": "https://omnirisk.io/developer/docs#errors"
  }
}
```

| Code                  | HTTP | Meaning                                                  |
|-----------------------|------|----------------------------------------------------------|
| BAD_REQUEST           | 400  | Malformed request — check parameters                     |
| UNAUTHORIZED          | 401  | Missing or invalid x-api-key                             |
| FORBIDDEN             | 403  | Key valid but lacks permission for this resource          |
| NOT_FOUND             | 404  | Resource does not exist                                  |
| CONFLICT              | 409  | Resource already exists (e.g. duplicate key name)         |
| VALIDATION_ERROR      | 422  | Parameter values failed schema validation                |
| RATE_LIMITED          | 429  | Too many requests — honour Retry-After                   |
| PAYMENT_REQUIRED      | 402  | Free quota exhausted — upgrade required                  |
| PREMIUM_REQUIRED      | 403  | Endpoint requires Pro or Pro+ plan                       |
| INTERNAL_ERROR        | 500  | Unexpected server error — retry with exponential back-off |
| UPSTREAM_ERROR        | 502  | On-chain data provider returned an error                 |
| UPSTREAM_UNAVAILABLE  | 503  | On-chain data provider temporarily unavailable           |

---

## 6. Endpoints — System

---

### GET /v1/health

Health check. No authentication required.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/health
```

**Example response (200):**
```json
{
  "status": "ok",
  "version": "1.14.2",
  "uptime_seconds": 3724891,
  "timestamp": "2026-05-20T10:00:00Z"
}
```

---

## 7. Endpoints — Developer (API Key Management)

---

### GET /v1/developer/api-keys

List all API keys for the authenticated account.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/developer/api-keys \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "keys": [
    {
      "id": "key_01hwz8qrbx",
      "name": "production-server",
      "prefix": "ri_live_k7mxq2",
      "created_at": "2026-03-10T08:22:00Z",
      "last_used_at": "2026-05-20T09:58:00Z",
      "status": "active"
    },
    {
      "id": "key_02abc9srcy",
      "name": "staging",
      "prefix": "ri_live_p9nyzr",
      "created_at": "2026-04-01T12:00:00Z",
      "last_used_at": null,
      "status": "active"
    }
  ]
}
```

---

### POST /v1/developer/api-keys

Create a new API key. The full secret is returned only once — store it immediately.

**Request body (JSON):**

| Field | Type   | Required | Description                    |
|-------|--------|----------|--------------------------------|
| name  | string | yes      | Human-readable label for the key (max 64 chars) |

**Example request:**
```bash
curl -X POST https://api.omnirisk.io/v1/developer/api-keys \
  -H "x-api-key: ri_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'
```

**Example response (201):**
```json
{
  "id": "key_03xyzt1uvw",
  "name": "my-agent",
  "key": "ri_live_q2mrp5.b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1",
  "prefix": "ri_live_q2mrp5",
  "created_at": "2026-05-20T10:05:00Z"
}
```

> **Note:** The `key` field is never returned again after creation.

---

### DELETE /v1/developer/api-keys/{keyId}

Revoke an API key immediately.

**Path parameters:**

| Parameter | Type   | Description      |
|-----------|--------|------------------|
| keyId     | string | ID of the key to revoke |

**Example request:**
```bash
curl -X DELETE https://api.omnirisk.io/v1/developer/api-keys/key_03xyzt1uvw \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "id": "key_03xyzt1uvw",
  "status": "revoked",
  "revoked_at": "2026-05-20T10:07:00Z"
}
```

---

### POST /v1/developer/api-keys/{keyId}/rotate

Rotate an API key. A new key is issued immediately. The old key remains valid for 24 hours to allow
migration of downstream services without downtime.

**Path parameters:**

| Parameter | Type   | Description       |
|-----------|--------|-------------------|
| keyId     | string | ID of the key to rotate |

**Example request:**
```bash
curl -X POST https://api.omnirisk.io/v1/developer/api-keys/key_01hwz8qrbx/rotate \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "new_key": {
    "id": "key_04newid567",
    "key": "ri_live_r8stv2.c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2",
    "prefix": "ri_live_r8stv2",
    "created_at": "2026-05-20T10:09:00Z"
  },
  "old_key": {
    "id": "key_01hwz8qrbx",
    "expires_at": "2026-05-21T10:09:00Z"
  }
}
```

---

### GET /v1/developer/usage

30-day usage statistics across all API keys.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/developer/usage \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "period": {
    "from": "2026-04-20T00:00:00Z",
    "to": "2026-05-20T00:00:00Z"
  },
  "total_requests": 18472,
  "quota": {
    "tier": "pro",
    "monthly_limit": 500000,
    "used": 18472,
    "remaining": 481528
  },
  "daily": [
    { "date": "2026-05-19", "requests": 1204 },
    { "date": "2026-05-18", "requests": 987 }
  ]
}
```

---

### GET /v1/developer/api-keys/{keyId}/usage

Per-key usage statistics for the past 30 days.

**Path parameters:**

| Parameter | Type   | Description       |
|-----------|--------|-------------------|
| keyId     | string | ID of the key     |

**Example request:**
```bash
curl https://api.omnirisk.io/v1/developer/api-keys/key_01hwz8qrbx/usage \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "key_id": "key_01hwz8qrbx",
  "period": {
    "from": "2026-04-20T00:00:00Z",
    "to": "2026-05-20T00:00:00Z"
  },
  "total_requests": 14221,
  "endpoints": {
    "/v1/token/analyze": 9801,
    "/v1/market/overview": 2104,
    "/v1/wallet/analyze": 2316
  }
}
```

---

## 8. Endpoints — Token

---

### GET /v1/token/analyze

Analyze a single token and return a risk score (0-100) and label.

**Query parameters:**

| Parameter | Type   | Required | Description                                       |
|-----------|--------|----------|---------------------------------------------------|
| chain     | string | yes      | Chain identifier (eth, bsc, sol, base, arb, poly, avax, ftm) |
| address   | string | yes      | Token contract address (0x hex for EVM, base58 for Solana) |

**Example request:**
```bash
curl -G https://api.omnirisk.io/v1/token/analyze \
  -H "x-api-key: ri_live_YOUR_KEY" \
  --data-urlencode "chain=eth" \
  --data-urlencode "address=0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"
```

**Example response (200):**
```json
{
  "chain": "eth",
  "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
  "score": 72.4,
  "label": "caution",
  "signals": [
    {
      "id": "low_liquidity",
      "severity": "medium",
      "weight": 0.28,
      "description": "24h liquidity depth is below recommended threshold"
    },
    {
      "id": "whale_concentration",
      "severity": "high",
      "weight": 0.41,
      "description": "Top 10 holders control 68% of supply"
    }
  ],
  "meta": {
    "name": "Uniswap",
    "symbol": "UNI",
    "price_usd": 7.31,
    "market_cap_usd": 5510000000,
    "liquidity_usd": 48200000
  },
  "cached_at": "2026-05-20T10:14:00Z"
}
```

**Score labels:**

| Score range | Label    |
|-------------|----------|
| 0–24        | safe     |
| 25–49       | caution  |
| 50–74       | risky    |
| 75–100      | critical |

---

### POST /v1/token/scan

Batch analyze up to 20 tokens in a single request.

**Request body (JSON):**

| Field  | Type  | Required | Description                          |
|--------|-------|----------|--------------------------------------|
| tokens | array | yes      | Array of `{ chain, address }` objects (max 20) |

**Example request:**
```bash
curl -X POST https://api.omnirisk.io/v1/token/scan \
  -H "x-api-key: ri_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokens": [
      { "chain": "eth", "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984" },
      { "chain": "bsc", "address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c" }
    ]
  }'
```

**Example response (200):**
```json
{
  "results": [
    {
      "chain": "eth",
      "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
      "score": 72.4,
      "label": "caution",
      "meta": { "name": "Uniswap", "symbol": "UNI", "price_usd": 7.31 }
    },
    {
      "chain": "bsc",
      "address": "0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c",
      "score": 18.1,
      "label": "safe",
      "meta": { "name": "Wrapped BNB", "symbol": "WBNB", "price_usd": 601.20 }
    }
  ],
  "processed": 2,
  "failed": 0,
  "cached_at": "2026-05-20T10:15:00Z"
}
```

---

### GET /v1/token/{chain}/{address}/meta

Token metadata: name, symbol, price, liquidity, holder count.

**Path parameters:**

| Parameter | Type   | Description          |
|-----------|--------|----------------------|
| chain     | string | Chain identifier      |
| address   | string | Token contract address |

**Example request:**
```bash
curl https://api.omnirisk.io/v1/token/eth/0x1f9840a85d5af5bf1d1762f925bdaddc4201f984/meta \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "chain": "eth",
  "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
  "name": "Uniswap",
  "symbol": "UNI",
  "decimals": 18,
  "total_supply": "1000000000000000000000000000",
  "circulating_supply_usd": 5510000000,
  "price_usd": 7.31,
  "price_change_24h": -2.14,
  "volume_24h_usd": 98400000,
  "liquidity_usd": 48200000,
  "holder_count": 342819,
  "contract_verified": true,
  "deploy_timestamp": "2020-09-17T01:00:00Z"
}
```

---

### GET /v1/token/{chain}/{address}/explanation

AI-generated narrative explanation of the token's risk profile.

**Path parameters:**

| Parameter | Type   | Description          |
|-----------|--------|----------------------|
| chain     | string | Chain identifier      |
| address   | string | Token contract address |

**Example request:**
```bash
curl https://api.omnirisk.io/v1/token/eth/0x1f9840a85d5af5bf1d1762f925bdaddc4201f984/explanation \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "chain": "eth",
  "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
  "score": 72.4,
  "label": "caution",
  "explanation": "UNI carries a moderate-to-high risk score of 72.4 primarily driven by whale concentration: the top 10 holders control approximately 68% of the circulating supply, making the token susceptible to large sell-off events. Liquidity depth has fallen 34% over the past 30 days and currently sits below the $50M threshold the OmniRisk model considers healthy for a token of this market cap. On the positive side, the contract is verified, the protocol has a 5-year track record, and there are no rug-pull signals in the deployer wallet history.",
  "generated_at": "2026-05-20T10:16:00Z",
  "model": "omnirisk-explain-v2"
}
```

> **Note:** This endpoint is available on Pro and Pro+ plans only. Free tier receives `PREMIUM_REQUIRED`.

---

### GET /v1/token/search

Search for tokens by name or symbol.

**Query parameters:**

| Parameter | Type   | Required | Description                   |
|-----------|--------|----------|-------------------------------|
| q         | string | yes      | Search term (min 2 chars)     |
| chain     | string | no       | Filter by chain (default: all) |
| limit     | int    | no       | Max results (default: 20, max: 100) |

**Example request:**
```bash
curl -G https://api.omnirisk.io/v1/token/search \
  -H "x-api-key: ri_live_YOUR_KEY" \
  --data-urlencode "q=uniswap" \
  --data-urlencode "chain=eth"
```

**Example response (200):**
```json
{
  "results": [
    {
      "chain": "eth",
      "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
      "name": "Uniswap",
      "symbol": "UNI",
      "price_usd": 7.31,
      "score": 72.4,
      "label": "caution"
    }
  ],
  "total": 1,
  "query": "uniswap"
}
```

---

### GET /v1/token/whales

Recent whale movements — large on-chain transfers above the detection threshold.

**Query parameters:**

| Parameter | Type   | Required | Description                              |
|-----------|--------|----------|------------------------------------------|
| chain     | string | no       | Filter by chain (default: all)            |
| min_usd   | number | no       | Minimum USD value (default: 1000000)     |
| limit     | int    | no       | Max results (default: 50, max: 200)      |

**Example request:**
```bash
curl -G https://api.omnirisk.io/v1/token/whales \
  -H "x-api-key: ri_live_YOUR_KEY" \
  --data-urlencode "chain=eth" \
  --data-urlencode "min_usd=5000000"
```

**Example response (200):**
```json
{
  "movements": [
    {
      "tx_hash": "0xabc123def456...",
      "chain": "eth",
      "token": { "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "symbol": "USDT" },
      "from": "0x28c6c06298d514db089934071355e5743bf21d60",
      "to": "0x21a31ee1afc51d94c2efccaa2092ad1028285549",
      "amount_usd": 12400000,
      "timestamp": "2026-05-20T09:44:00Z",
      "risk_flag": "exchange_outflow"
    }
  ],
  "count": 1,
  "as_of": "2026-05-20T10:17:00Z"
}
```

---

### GET /v1/token/alerts

Active token risk alerts feed.

**Query parameters:**

| Parameter | Type   | Required | Description                              |
|-----------|--------|----------|------------------------------------------|
| chain     | string | no       | Filter by chain (default: all)            |
| severity  | string | no       | Filter: low, medium, high, critical       |
| limit     | int    | no       | Max results (default: 30, max: 100)      |

**Example request:**
```bash
curl -G https://api.omnirisk.io/v1/token/alerts \
  -H "x-api-key: ri_live_YOUR_KEY" \
  --data-urlencode "severity=high"
```

**Example response (200):**
```json
{
  "alerts": [
    {
      "id": "alt_01jxkp7mz3",
      "chain": "bsc",
      "token": { "address": "0xdeadbeef...", "symbol": "REKT" },
      "type": "rug_pull_signal",
      "severity": "critical",
      "message": "LP locked tokens unlocking in 12 hours — 98% of liquidity at risk",
      "triggered_at": "2026-05-20T09:30:00Z"
    }
  ],
  "count": 1,
  "as_of": "2026-05-20T10:17:00Z"
}
```

---

## 9. Endpoints — Market

---

### GET /v1/market/overview

Global crypto market overview: total market cap, dominance, volume.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/market/overview \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "total_market_cap_usd": 2840000000000,
  "total_volume_24h_usd": 98200000000,
  "btc_dominance": 54.3,
  "eth_dominance": 17.1,
  "market_cap_change_24h": 1.8,
  "active_tokens": 14821,
  "fear_greed_index": 64,
  "fear_greed_label": "greed",
  "timestamp": "2026-05-20T10:00:00Z"
}
```

---

### GET /v1/market/signals

Active market risk signals — macro-level flags currently elevated.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/market/signals \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "signals": [
    {
      "id": "funding_rate_spike",
      "severity": "high",
      "title": "Perpetual funding rates spiked above 0.1%",
      "description": "Elevated funding rates indicate excessive long leverage across major perp venues. Historical correlation with short-term correction is 0.72.",
      "triggered_at": "2026-05-20T06:00:00Z",
      "active": true
    },
    {
      "id": "stablecoin_outflow",
      "severity": "medium",
      "title": "Net stablecoin outflows from CEXes detected",
      "description": "USDT and USDC net outflow from top-5 CEXes exceeded $800M in 24h.",
      "triggered_at": "2026-05-19T22:00:00Z",
      "active": true
    }
  ],
  "count": 2,
  "as_of": "2026-05-20T10:18:00Z"
}
```

---

### GET /v1/market/regime

Current macro market regime classification.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/market/regime \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "regime": "bull",
  "confidence": 0.81,
  "label": "Risk-On Bull",
  "description": "Broad uptrend with strong BTC dominance decline and altcoin rotation. On-chain accumulation patterns consistent with mid-cycle expansion.",
  "previous_regime": "sideways",
  "regime_since": "2026-04-11T00:00:00Z",
  "as_of": "2026-05-20T10:00:00Z"
}
```

**Regime values:** `bull` | `bear` | `sideways` | `volatile`

---

### GET /v1/market/heatmap

Risk heatmap — per-chain and per-sector aggregate risk scores.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/market/heatmap \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "chains": [
    { "chain": "eth", "avg_risk_score": 41.2, "token_count": 4821, "label": "caution" },
    { "chain": "sol", "avg_risk_score": 58.7, "token_count": 2904, "label": "risky" },
    { "chain": "bsc", "avg_risk_score": 63.1, "token_count": 3102, "label": "risky" }
  ],
  "sectors": [
    { "sector": "DeFi", "avg_risk_score": 47.3, "label": "caution" },
    { "sector": "Meme", "avg_risk_score": 81.4, "label": "critical" },
    { "sector": "L1/L2", "avg_risk_score": 29.8, "label": "safe" }
  ],
  "as_of": "2026-05-20T10:00:00Z"
}
```

---

### GET /v1/market/trending

Trending tokens ranked by search and on-chain activity in the last 24 hours.

**Query parameters:**

| Parameter | Type   | Required | Description                              |
|-----------|--------|----------|------------------------------------------|
| chain     | string | no       | Filter by chain (default: all)            |
| limit     | int    | no       | Max results (default: 20, max: 100)      |

**Example request:**
```bash
curl -G https://api.omnirisk.io/v1/market/trending \
  -H "x-api-key: ri_live_YOUR_KEY" \
  --data-urlencode "limit=5"
```

**Example response (200):**
```json
{
  "tokens": [
    {
      "rank": 1,
      "chain": "sol",
      "address": "So11111111111111111111111111111111111111112",
      "name": "Wrapped SOL",
      "symbol": "WSOL",
      "price_usd": 172.40,
      "price_change_24h": 8.3,
      "score": 22.1,
      "label": "safe",
      "trending_score": 98.4
    }
  ],
  "count": 1,
  "as_of": "2026-05-20T10:19:00Z"
}
```

---

### GET /v1/market/intelligence

Macro intelligence digest — curated risk insights from OmniRisk analysts and models.

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/market/intelligence \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "digest": [
    {
      "id": "int_01jxlq8na4",
      "title": "BTC miner outflows signal potential short-term sell pressure",
      "summary": "Miner wallets have transferred ~4,200 BTC to exchanges in the past 48h — the highest 48h outflow since January 2026. Historically precedes a 3-7% correction within 5 days.",
      "confidence": 0.74,
      "severity": "medium",
      "published_at": "2026-05-20T07:00:00Z"
    }
  ],
  "count": 1,
  "as_of": "2026-05-20T10:00:00Z"
}
```

> **Note:** This endpoint requires Pro or Pro+ plan.

---

## 10. Endpoints — Wallet

---

### POST /v1/wallet/analyze

Analyze a wallet address and return a risk profile.

**Request body (JSON):**

| Field   | Type   | Required | Description                            |
|---------|--------|----------|----------------------------------------|
| chain   | string | yes      | Chain identifier                        |
| address | string | yes      | Wallet address                          |

**Example request:**
```bash
curl -X POST https://api.omnirisk.io/v1/wallet/analyze \
  -H "x-api-key: ri_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chain": "eth", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'
```

**Example response (200):**
```json
{
  "chain": "eth",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "risk_score": 14.2,
  "risk_label": "safe",
  "profile": {
    "wallet_age_days": 2847,
    "tx_count": 1204,
    "unique_tokens_held": 38,
    "defi_interactions": 412,
    "nft_count": 7,
    "first_tx": "2018-11-21T15:34:00Z",
    "last_tx": "2026-05-19T08:22:00Z"
  },
  "flags": [],
  "portfolio_risk": {
    "avg_token_score": 31.8,
    "high_risk_exposure_pct": 4.2,
    "top_holdings": [
      { "symbol": "ETH", "value_usd": 184200, "score": 12.1 },
      { "symbol": "UNI", "value_usd": 28400, "score": 72.4 }
    ]
  },
  "analyzed_at": "2026-05-20T10:20:00Z"
}
```

---

### GET /v1/wallet/risk-matrix

Wallet risk matrix — cross-sectional risk breakdown across a watchlist of wallets (uses the wallets
stored in your OmniRisk account's watchlist).

**Parameters:** none

**Example request:**
```bash
curl https://api.omnirisk.io/v1/wallet/risk-matrix \
  -H "x-api-key: ri_live_YOUR_KEY"
```

**Example response (200):**
```json
{
  "wallets": [
    {
      "chain": "eth",
      "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "label": "vitalik.eth",
      "risk_score": 14.2,
      "risk_label": "safe",
      "portfolio_value_usd": 220000
    },
    {
      "chain": "eth",
      "address": "0xbe0eb53f46cd790cd13851d5eff43d12404d33e8",
      "label": "Binance Hot Wallet",
      "risk_score": 33.7,
      "risk_label": "caution",
      "portfolio_value_usd": 2100000000
    }
  ],
  "matrix_as_of": "2026-05-20T10:00:00Z"
}
```

---

## 11. Agentic Usage Notes

This section is specifically for AI agents, LLM-powered workflows, and autonomous tools.

### Discovery flow

1. Fetch `https://omnirisk.io/llms.txt` — small summary, always start here.
2. If you need full parameter details, fetch `https://omnirisk.io/llms-full.txt` (this file).
3. For OpenAPI-compatible tooling, use `https://omnirisk.io/openapi.json`.

### Environment variable pattern

Always retrieve the API key from the environment:

```python
import os
import requests

api_key = os.environ["OMNIRISK_API_KEY"]
response = requests.get(
    "https://api.omnirisk.io/v1/token/analyze",
    params={"chain": "eth", "address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"},
    headers={"x-api-key": api_key},
)
data = response.json()
```

### Rate limit awareness

Check `X-RateLimit-Remaining` on every response. If it reaches 0, wait until `X-RateLimit-Reset`
before making the next request. On HTTP 429, read `Retry-After` and sleep for that duration.

```python
remaining = int(response.headers.get("X-RateLimit-Remaining", 1))
reset_at = int(response.headers.get("X-RateLimit-Reset", 0))

if remaining == 0:
    import time
    sleep_secs = max(reset_at - time.time(), 1)
    time.sleep(sleep_secs)
```

### Batch preference

Prefer `POST /v1/token/scan` (up to 20 tokens) over repeated `GET /v1/token/analyze` calls.
This reduces round-trips and rate-limit consumption.

### Error retry policy

| Error code           | Retry? | Strategy                                  |
|----------------------|--------|-------------------------------------------|
| RATE_LIMITED         | Yes    | Sleep Retry-After seconds, then retry      |
| UPSTREAM_ERROR       | Yes    | Exponential back-off, max 3 retries        |
| UPSTREAM_UNAVAILABLE | Yes    | Exponential back-off, max 5 retries        |
| INTERNAL_ERROR       | Yes    | Exponential back-off, max 3 retries        |
| UNAUTHORIZED         | No     | Fix the key — do not retry automatically   |
| PAYMENT_REQUIRED     | No     | Upgrade plan — do not retry automatically  |
| PREMIUM_REQUIRED     | No     | Upgrade plan — do not retry automatically  |
| VALIDATION_ERROR     | No     | Fix request parameters                     |

---

## 12. Pagination

Endpoints that return lists (search, whales, alerts, trending, intelligence) accept `limit`
parameters. Currently the API uses **offset-free result windows** — there is no cursor or
page token. To fetch more results, increase the `limit` parameter up to the documented maximum.

Future versions may introduce cursor-based pagination; the response will include a `next_cursor`
field when that is available. Check `https://omnirisk.io/openapi.json` for the latest schema.

---

*Last updated: 2026-05-20 | OmniRisk API v1*
*Source: https://omnirisk.io/llms-full.txt*