API

Overview and authentication

The Iris engine as a JSON API: the same analyses and traces as the site, for your own code.

Base URL

Every route lives under one base URL. Requests and responses are JSON; send Content-Type: application/json with a body.

base url

1https://iriscan.app/api

Authentication

Create a key in Account → API (see API keys) and send it with every request, either way:

headers

1Authorization: Bearer iris_live_…2# or3x-api-key: iris_live_…

/status is public. Everything else answers 401 without a valid key.

Keep keys secret

A key spends your account's analyses and traces. Keep it on your server, never in a web page or an app people can download. Revoke it at once if it leaks.

Your first call

analyze.sh

1curl -X POST https://iriscan.app/api/analyze \2  -H "Authorization: Bearer $IRIS_KEY" \3  -H "Content-Type: application/json" \4  -d '{ "address": "sy88tvipKfaCTuVVeU2PczPa88hqgPfKnYQyCHboHP8" }'

analyze.py

1import os2import requests3 4profile = requests.post(5    "https://iriscan.app/api/analyze",6    headers={"Authorization": f"Bearer {os.environ['IRIS_KEY']}"},7    json={"address": "sy88tvipKfaCTuVVeU2PczPa88hqgPfKnYQyCHboHP8"},8    timeout=130,9).json()10 11print(profile["identity"]["type"], profile["risk"]["level"])

analyze.ts

1const res = await fetch("https://iriscan.app/api/analyze", {2  method: "POST",3  headers: {4    Authorization: `Bearer ${process.env.IRIS_KEY}`,5    "Content-Type": "application/json",6  },7  body: JSON.stringify({ address: "sy88tvipKfaCTuVVeU2PczPa88hqgPfKnYQyCHboHP8" }),8});9 10if (!res.ok) throw new Error((await res.json()).error);11const profile = await res.json();

Routes

Route	Does	Cost
POST /analyze	Identity, risk and evidence for a wallet, a program or a token.	1 analysis, 3 above 1,000 transactions
POST /trace	Where a transfer through a mixer or an exchange came out.	1 trace
GET /status	The health of the API and what it relies on.	Free, public
`GET /billing/account`	Your plan, allowance left and credits.	Free
`GET /billing/usage/{days}`	What you used per day, 7 to 365 days back.	Free

Credits left

Every /analyze and /trace response, failures included, carries an x-iris-credits header: what your account has left after the call.

x-iris-credits

1{2  "plan": "api_pro",3  "plan_name": "API Pro",4  "cycle": "monthly",5  "analyses_left": 9412,6  "traces_left": 488,7  "pack_credits": 0,8  "period_end": "2026-10-29T00:00:00Z",9  "paid_until": "2026-10-29T00:00:00Z"10}