Documentation

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.com

Is 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.

Get a free API key

600 requests per minute instead of 60. Free.

Used only to contact you about the API: changes, limits and abuse. Not shown publicly and never sold.

  • 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

TierLimitCounted perHow
Anonymous60 / minuteper IP addressNo key needed.
Registered600 / minuteper keyFree. Send X-API-Key.
Badge images300 / minuteper IP addressAutomatic for GET /badge/*. READMEs load in bursts.

Limits use a sliding one-minute window. /health and / are never limited. Every response carries:

HeaderMeaning
X-RateLimit-LimitRequests allowed per minute for your tier.
X-RateLimit-RemainingRequests left in the current window.
X-RateLimit-Tieranonymous, registered or badge.
Retry-AfterOn a 429 only: seconds until you can retry.
Be kind to the free tier. Responses change at most every few minutes (scores every four hours), so caching for a minute or more loses you nothing. On a 429, wait Retry-After seconds instead of retrying immediately.

Conventions

  • null means not measured, never 0. A field is null when 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.012 is 1.2%) except fields named _pct, which are percent.
  • Timestamps are ISO 8601 in UTC.
  • Third-party data (market, venues) carries source and fetched_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

StatusWhen
400A malformed value, such as an address that is not 0x plus 40 hex characters, or an untracked token.
401The X-API-Key is invalid or revoked.
404No tracked project or contract with that id or address.
422A parameter is out of range (for example days=500) or a request body is invalid.
429Rate limit exceeded. Read Retry-After.
503A data source is temporarily unavailable. The API says so rather than returning an empty list that would look like no activity.
Error body
{ "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.
ParameterInTypeDescription
daysqueryintegerNumber 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.
ParameterInTypeDescription
daysqueryintegerNumber of UTC days, 1 to 90. Default 30.
tokenquerystringUSDC, 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.

ParameterInTypeDescription
daysqueryintegerNumber of UTC days, 1 to 30. Default 7.
limitqueryintegerHow 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.

ParameterInTypeDescription
project_id *pathstringProject 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.

ParameterInTypeDescription
address *pathstringA 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.
ParameterInTypeDescription
project_id *pathstringProject slug, e.g. the id field of /projects.
daysqueryintegerNumber 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.

ParameterInTypeDescription
limitqueryintegerHow 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.

ParameterInTypeDescription
project_id *pathstringProject 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.

ParameterInTypeDescription
project_id *pathstringProject slug, e.g. the id field of /projects.
limitqueryintegerHow 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.

ParameterInTypeDescription
limitqueryintegerHow 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.

ParameterInTypeDescription
limitqueryintegerHow 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).
ParameterInTypeDescription
kindquerystringdex 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.
ParameterInTypeDescription
name *bodystringWhat you are building, 2 to 60 characters.
email *bodystringContact 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.
ParameterInTypeDescription
contract_address *bodystring0x address of the contract.
proposed_namebodystringUp to 500 characters.
proposed_categorybodystringUp to 500 characters.
socialsbodyobjectLinks, for the reviewer.
submitter_contactbodystringHow to reach you.
notebodystringAnything 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.
ParameterInTypeDescription
project_id *pathstringProject 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)
API reference · Isogram