API reference.
A read-only REST API over everything the dashboard shows. JSON over HTTPS, open CORS, no key needed to start. The dashboard itself is a client of this API.
Quickstart
Base URL:
https://isogramapi.onrender.comIs the data fresh, then what is on Arc:
curl https://isogramapi.onrender.com/metrics/status
curl "https://isogramapi.onrender.com/metrics/network/daily?days=7"
curl "https://isogramapi.onrender.com/projects"The same in JavaScript, reading the rate-limit headers (browsers can read them; CORS exposes them):
const res = await fetch("https://isogramapi.onrender.com/metrics/network/daily?days=7", {
headers: { "X-API-Key": process.env.ISOGRAM_API_KEY }, // optional
});
if (res.status === 429) {
const wait = Number(res.headers.get("Retry-After")); // seconds
}
console.log(res.headers.get("X-RateLimit-Remaining"), await res.json());A browser-friendly, interactive reference generated from the code is also available as Swagger UI.
API keys
You do not need a key to call the API, but a free key raises your limit tenfold and keeps your traffic separate from everyone else sharing your network address. Send it as the X-API-Key header.
- The key is shown once. Only a hash is stored, so a lost key cannot be recovered; create another.
- Treat it like a password: keep it on your server, not in front-end code or a public repo. If it leaks, create a new one and ask for the old one (identified by its first 8 characters) to be revoked.
- A wrong or revoked key gets
401, never a silent downgrade, so typos are noticed. Revocation takes effect within a minute. - Up to 5 new keys per address per day and 3 active keys per email. Need more than 600 a minute? Open an issue on GitHub with what you are building.
- Your email. It is required so we can contact you about the API: changes, limits and abuse. It is not verified, never shown publicly, never returned by the API, and not sold or shared. To have it deleted along with your key, ask on GitHub.
Rate limits
| Tier | Limit | Counted per | How |
|---|---|---|---|
| Anonymous | 60 / minute | per IP address | No key needed. |
| Registered | 600 / minute | per key | Free. Send X-API-Key. |
| Badge images | 300 / minute | per IP address | Automatic for GET /badge/*. READMEs load in bursts. |
Limits use a sliding one-minute window. /health and / are never limited. Every response carries:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute for your tier. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Tier | anonymous, registered or badge. |
Retry-After | On a 429 only: seconds until you can retry. |
429, wait Retry-After seconds instead of retrying immediately.Conventions
- null means not measured, never 0. A field is
nullwhen it does not apply (a token has no TVL) or was not recorded. Handle it explicitly. - Days are UTC calendar days, written
YYYY-MM-DD, oldest first. The latest day is usually partial (partial: true). Days the pipeline did not cover are absent, not zero-filled. - USDC amounts are in USDC (the 6-decimal view), as plain numbers. USDC is Arc's native gas asset; the 18-decimal native view and the 6-decimal ERC-20 view are the same funds and are never added together.
- Ratios are fractions (
failed_rate: 0.012is 1.2%) except fields named_pct, which are percent. - Timestamps are ISO 8601 in UTC.
- Third-party data (
market, venues) carriessourceandfetched_at, and is treated as absent once stale. - Stability. The API is pre-1.0 (version 0.3). New fields may be added; an existing field will not change meaning without a note in the repository changelog.
- CORS is open (
*) for GET and POST, without credentials, so you can call it from a browser. Prefer a server-side call when you use a key.
Errors
| Status | When |
|---|---|
400 | A malformed value, such as an address that is not 0x plus 40 hex characters, or an untracked token. |
401 | The X-API-Key is invalid or revoked. |
404 | No tracked project or contract with that id or address. |
422 | A parameter is out of range (for example days=500) or a request body is invalid. |
429 | Rate limit exceeded. Read Retry-After. |
503 | A data source is temporarily unavailable. The API says so rather than returning an empty list that would look like no activity. |
{ "detail": "No tracked project 'nope'" }The free hosting tier can take 5 to 20 seconds to wake after a quiet period. Retry once if your first request times out.
Status
Check freshness before trusting anything marked latest.
GET/health
Liveness probe. Never rate limited, safe for uptime monitors. HEAD is accepted too.
curl "https://isogramapi.onrender.com/health"Example response (shape exact, values illustrative)
{ "status": "ok" }GET/metrics/status
How fresh the data is: the last block ingestion applied and how far behind now that is.
- status is live when the lag is under 10 minutes, behind when ingestion is catching up or stalled, unknown before the first batch.
- Days after data_through are incomplete in every daily series.
curl "https://isogramapi.onrender.com/metrics/status"Example response (shape exact, values illustrative)
{
"status": "live",
"last_block_number": 25537874,
"data_through": "2026-10-12T06:16:36+00:00",
"lag_seconds": 7,
"checkpoint_updated_at": "2026-10-12T06:16:37.946836+00:00"
}Network
Chain-wide activity, one row per UTC day.
GET/stats
Headline totals across tracked projects, for a stat strip.
curl "https://isogramapi.onrender.com/stats"Example response (shape exact, values illustrative)
{
"total_projects": 876,
"total_scored": 29,
"total_tvl_usd": 1520000.5,
"avg_score": 0.41,
"total_volume_7d": 18200.4,
"total_tx_7d": 9120000,
"total_unique_users_7d": 154000,
"computed_at": "2026-10-12T04:00:12+00:00"
}GET/metrics/network/daily
Chain-wide daily totals: transactions, failures, USDC gas, deployments, blocks, transfers, active senders.
- Oldest first. A day the pipeline did not cover is absent, never zero-filled.
- partial is true for days still accruing. source is raw_backfill for early days that predate failure, deployment and block tracking (those fields are null).
- failed_rate and avg_gas_per_tx_usdc are derived: failed / transactions and gas / transactions.
| Parameter | In | Type | Description |
|---|---|---|---|
days | query | integer | Number of UTC days, 1 to 90. Default 30. |
curl "https://isogramapi.onrender.com/metrics/network/daily?days=7"Example response (shape exact, values illustrative)
[
{
"day": "2026-10-11",
"tx_count": 1028753,
"failed_tx_count": 3086,
"failed_rate": 0.003,
"usdc_gas_paid": 4210.55,
"avg_gas_per_tx_usdc": 0.0041,
"contract_creations": 412,
"blocks": 170112,
"token_transfer_count": 2201455,
"active_addresses": 98211,
"source": "rollup",
"partial": false
}
]GET/metrics/tokens/daily
Daily transfer count and volume for the tracked tokens (USDC, EURC, USYC), each in its own 6-decimal units.
- USDC volume is gross movement taken once from Arc's native system log: every transfer counts, including hops through routers, and mint and burn are excluded. It is not economic volume.
- Volumes of different tokens are never added together.
| Parameter | In | Type | Description |
|---|---|---|---|
days | query | integer | Number of UTC days, 1 to 90. Default 30. |
token | query | string | USDC, EURC, USYC or a tracked token address. Omit for all three. |
curl "https://isogramapi.onrender.com/metrics/tokens/daily?days=7&token=USDC"Example response (shape exact, values illustrative)
[
{
"day": "2026-10-11",
"token_address": "0x3600000000000000000000000000000000000000",
"symbol": "USDC",
"transfer_count": 2201455,
"volume": 205800000.12,
"avg_transfer_size": 93.48
}
]GET/metrics/contracts/top
Top contracts by USDC gas over a window, with each one's share of all network gas and its project when tracked.
| Parameter | In | Type | Description |
|---|---|---|---|
days | query | integer | Number of UTC days, 1 to 30. Default 7. |
limit | query | integer | How many contracts, 1 to 100. Default 20. |
curl "https://isogramapi.onrender.com/metrics/contracts/top?days=7&limit=5"Example response (shape exact, values illustrative)
[
{
"contract_address": "0x0000000000000000000000000000000000000001",
"project_id": "example-project",
"project_name": "Example Project",
"category": "dex",
"tx_count": 900000,
"failed_tx_count": 9000,
"failed_rate": 0.01,
"usdc_gas": 1500.0,
"gas_share": 0.12
}
]Projects
Everything Isogram tracks, with the metrics that apply to each type.
GET/projects
Every tracked project with its latest figures. Market data, holders and links are included where known.
- segment decides which fields mean something: score and tvl_usd exist for defi only and are null elsewhere (null means not applicable, never 0).
- tier is curated for hand-checked projects and discovered for automatically promoted ones. Discovered is not an endorsement.
- market is third-party (GeckoTerminal) and null when there is no fresh price. FDV and market cap are withheld unless quality is ok.
- The response is not paginated (a few hundred rows).
curl "https://isogramapi.onrender.com/projects"Example response (shape exact, values illustrative)
[
{
"id": "example-project",
"name": "Example Project",
"category": "token",
"segment": "token",
"tier": "discovered",
"score": null,
"tvl_usd": null,
"usdc_gas_7d": 412.307,
"unique_users_7d": 1893,
"tx_count_7d": 51210,
"failed_tx_7d": 604,
"failed_rate_7d": 0.0118,
"computed_at": "2026-10-12T04:00:12+00:00",
"market": {
"price_usd": 0.0412,
"fdv_usd": null,
"market_cap_usd": null,
"liquidity_usd": 6200,
"volume_24h_usd": 18400,
"price_change_24h_pct": 4.7,
"volume_7d_usd": 90100,
"quality": "thin",
"listed_on_coingecko": false,
"source": "geckoterminal",
"fetched_at": "2026-10-12T11:02:44+00:00"
},
"holders": 5120,
"socials": [{ "kind": "website", "url": "https://example.org", "curated": false }]
}
]GET/projects/{project_id}
One project, with its contract addresses.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id * | path | string | Project slug, e.g. the id field of /projects. |
curl "https://isogramapi.onrender.com/projects/example-project"Example response (shape exact, values illustrative)
{
"id": "example-project",
"name": "Example Project",
"category": "token",
"segment": "token",
"tier": "discovered",
"score": null,
"tvl_usd": null,
"usdc_gas_7d": 412.307,
"unique_users_7d": 1893,
"tx_count_7d": 51210,
"failed_tx_7d": 604,
"failed_rate_7d": 0.0118,
"computed_at": "2026-10-12T04:00:12+00:00",
"market": {
"price_usd": 0.0412,
"fdv_usd": null,
"market_cap_usd": null,
"liquidity_usd": 6200,
"volume_24h_usd": 18400,
"price_change_24h_pct": 4.7,
"volume_7d_usd": 90100,
"quality": "thin",
"listed_on_coingecko": false,
"source": "geckoterminal",
"fetched_at": "2026-10-12T11:02:44+00:00"
},
"holders": 5120,
"socials": [{ "kind": "website", "url": "https://example.org", "curated": false }],
"contracts": ["0x0000000000000000000000000000000000000001"],
"created_at": "2026-10-04T09:12:00+00:00"
}GET/projects/by-address/{address}
Which tracked project owns a contract address. 404 when none does, 400 when the address is malformed.
| Parameter | In | Type | Description |
|---|---|---|---|
address * | path | string | A 0x-prefixed, 40-hex-character address (any case). |
curl "https://isogramapi.onrender.com/projects/by-address/0x3600000000000000000000000000000000000000"Example response (shape exact, values illustrative)
{ "id": "usdc", "name": "USDC" }GET/projects/{project_id}/daily
One project's daily transactions, failures, USDC gas and unique senders.
- unique_users is null for days before the contract was tracked, not 0.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id * | path | string | Project slug, e.g. the id field of /projects. |
days | query | integer | Number of UTC days, 1 to 90. Default 30. |
curl "https://isogramapi.onrender.com/projects/example-project/daily?days=14"Example response (shape exact, values illustrative)
[
{
"day": "2026-10-11",
"tx_count": 7210,
"failed_tx_count": 84,
"failed_rate": 0.0117,
"usdc_gas": 58.2,
"unique_users": 312
}
]Rankings
Pre-sorted views of the same project objects returned by /projects.
GET/scores/top
Projects by Arc Native Score, highest first. Only DeFi protocols are scored.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | How many projects. Default 10. |
curl "https://isogramapi.onrender.com/scores/top?limit=5"Example response (shape exact, values illustrative)
[ { …project object… } ]GET/scores/{project_id}
One project's current score and its inputs.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id * | path | string | Project slug, e.g. the id field of /projects. |
curl "https://isogramapi.onrender.com/scores/example-project"Example response (shape exact, values illustrative)
{ …project object… }GET/scores/{project_id}/history
A project's score over time, one point per scoring run (every four hours), newest first.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id * | path | string | Project slug, e.g. the id field of /projects. |
limit | query | integer | How many points, 1 to 500. Default 100. |
curl "https://isogramapi.onrender.com/scores/example-project/history?limit=30"Example response (shape exact, values illustrative)
[
{
"computed_at": "2026-10-12T04:00:12+00:00",
"score": 0.62,
"tvl_usd": 1200000.0,
"usdc_gas_7d": 833.1,
"unique_users_7d": 2401
}
]GET/tvl/top
DeFi protocols by TVL, highest first. /tvl/{project_id} returns one project.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | How many projects. Default 10. |
curl "https://isogramapi.onrender.com/tvl/top?limit=5"Example response (shape exact, values illustrative)
[ { …project object… } ]GET/gas/top
Projects by trailing 7-day USDC gas, highest first. /gas/{project_id} returns one project.
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer | How many projects. Default 10. |
curl "https://isogramapi.onrender.com/gas/top?limit=5"Example response (shape exact, values illustrative)
[ { …project object… } ]DEX volume
Per-venue 24 hour volume (GeckoTerminal, third-party, refreshed hourly).
GET/venues
DEXes and launch platforms with 24h volume, biggest first.
- Anomalous pools (fewer than 10 traders in 24h, or volume above 25x reserves) are left out. The amount left out is reported in excluded_volume_usd, never hidden.
- truncated means the venue has more pools than the scan covers, so volume is a lower bound.
- share is relative to all venues, even when filtered by kind. 503 when the data is temporarily unavailable (never an empty list that would look like no trading).
| Parameter | In | Type | Description |
|---|---|---|---|
kind | query | string | dex or launchpad. Omit for both. |
curl "https://isogramapi.onrender.com/venues?kind=dex"Example response (shape exact, values illustrative)
[
{
"dex_id": "example-dex",
"name": "Example DEX",
"kind": "dex",
"volume_24h_usd": 250000.0,
"share": 0.1,
"active_pools": 270,
"sample_pools": 300,
"excluded_volume_usd": 0.0,
"excluded_pools": 0,
"truncated": false,
"top_pool_name": "WETH / USDC",
"top_pool_volume_usd": 90000.0,
"source": "geckoterminal",
"fetched_at": "2026-10-12T11:02:44+00:00"
}
]Writes
The only two public routes that create anything. Both are rate limited.
POST/keys
Create a free API key. The key is returned once and cannot be recovered; only its hash is stored.
- Limited to 5 new keys per address per day, and 3 active keys per email (409 beyond that). Use the form above, or call it directly.
| Parameter | In | Type | Description |
|---|---|---|---|
name * | body | string | What you are building, 2 to 60 characters. |
email * | body | string | Contact address, up to 254 characters. Used only to reach you about API changes, limits and abuse. Not verified, never shown publicly, never returned by the API. |
curl -X POST "https://isogramapi.onrender.com/keys" \
-H "Content-Type: application/json" \
-d '{"name": "Acme portfolio tracker", "email": "dev@acme.io"}'Example response (shape exact, values illustrative)
{
"api_key": "isg_Zk3…",
"id": 12,
"name": "Acme portfolio tracker",
"tier": "registered",
"rate_limit_per_minute": 600,
"created_at": "2026-10-13T09:00:00+00:00",
"note": "Store this key now. It is shown once and cannot be recovered. Send it as the X-API-Key header."
}POST/submit
Propose a contract for listing. It goes to a human review queue and is never listed automatically.
- Limited to 5 submissions per address per hour.
| Parameter | In | Type | Description |
|---|---|---|---|
contract_address * | body | string | 0x address of the contract. |
proposed_name | body | string | Up to 500 characters. |
proposed_category | body | string | Up to 500 characters. |
socials | body | object | Links, for the reviewer. |
submitter_contact | body | string | How to reach you. |
note | body | string | Anything the reviewer should know. |
curl -X POST "https://isogramapi.onrender.com/submit" \
-H "Content-Type: application/json" \
-d '{"contract_address": "0x0000000000000000000000000000000000000001", "proposed_name": "Example"}'Example response (shape exact, values illustrative)
{ "id": 41, "contract_address": "0x0000000000000000000000000000000000000001", "status": "pending", "created_at": "2026-10-13T09:00:00+00:00" }Badge
An embeddable SVG. See the badges guide for copy-paste snippets.
GET/badge/{project_id}.svg
An SVG badge with the project's Arc Native Score. DeFi protocols show a score or insufficient data; every other type says not scored.
- Cached for one hour (Cache-Control: max-age=3600). Has its own, larger rate limit so README images are not throttled.
| Parameter | In | Type | Description |
|---|---|---|---|
project_id * | path | string | Project slug, e.g. the id field of /projects. |
curl "https://isogramapi.onrender.com/badge/example-project.svg"Example response (shape exact, values illustrative)
<svg …> (image/svg+xml)