Authentication
Send your key as a Bearer token or an X-API-Key header. Keys are stored and checked by hash, carry only the scopes you grant, and can be expired or revoked at any time.
Authorization: Bearer <your API key>
Submit investigations from your intake, run wallet and entity checks on demand, watch wallets, follow freeze requests and referrals, and pull reviewed findings and released reports into the systems your team already uses.
curl -X POST https://chaintracelabs.com/api/v1/investigations \ -H "Authorization: Bearer $CT_KEY" \ -H "Content-Type: application/json" \ -d '{"blockchain":"tron","loss_txid":"8f3a…e21"}'
const res = await fetch('https://chaintracelabs.com/api/v1/investigations', { method: 'POST', headers: { Authorization: `Bearer ${CT_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ blockchain: 'tron', loss_txid: '8f3a…e21' }), });
import requests r = requests.post("https://chaintracelabs.com/api/v1/investigations", headers={"Authorization": f"Bearer {CT_KEY}"}, json={"blockchain": "tron", "loss_txid": "8f3a…e21"})
{ "data": { "case_ref": "CT-2048", … }, "meta": { "request_id": "…", "status_url": "…/investigations/CT-2048/status" } }
Send your key as a Bearer token or an X-API-Key header. Keys are stored and checked by hash, carry only the scopes you grant, and can be expired or revoked at any time.
Authorization: Bearer <your API key>
Check the service, the networks you can open cases on and what your key has left.
/healthCheck the API is upno key/chainsBlockchains you can open investigations onany key/usageThis key's hourly limit and your plan's remaining capacityusage:readOpen cases and follow them from tracing to review.
/investigationsYour firm's 100 most recently updated investigationsinvestigations:read/investigationsOpen a new investigation (returns 202 and a status link)investigations:create/investigations/{ref}One investigation with its trace summaryinvestigations:read/investigations/{ref}/statusTracing jobs and review stateinvestigations:read/investigations/{ref}/findingsEvidence-backed findingsinvestigations:read/investigations/{ref}/evidence-summaryCounts of evidence files, custody events and findings awaiting reviewinvestigations:read/investigations/{ref}/exchange-leadsWhere funds reached exchanges, with attribution and lineage confidenceinvestigations:read/investigations/{ref}/relatedOther cases in your firm that share wallets, contacts or wordinginvestigations:readRead the report summary once your team has released it.
/investigations/{ref}/reportReleased report summary (409 until the report is released)reports:readFollow freeze requests, police referrals, Live Pursuit and the custody log.
/investigations/{ref}/freeze-requestsFreeze and preservation requests sent to exchanges, with their statusactions:read/investigations/{ref}/law-enforcementPolice and regulator referrals, with reference numbers and follow-upsactions:read/investigations/{ref}/pursuitsLive Pursuit sessions and the wallets funds moved toactions:read/investigations/{ref}/custodyCustody log entries with their hash chain (newest 200)actions:readRun wallet risk (KYT) and entity (KYB) checks from your own systems.
/wallet-assessmentsRisk and attribution for one wallet (uses one wallet assessment)wallet:assess/entity-profilesProfile of a company or person (uses one entity profile)entity:profileManage watched wallets and read their alerts.
/monitoringMonitored wallets, recent alerts and totalsmonitoring:read/monitoringAdd a wallet to monitoring on one of your casesmonitoring:write/nigeria-checksNigeria fraud check of one phone, account, name, wallet or website, with a signed receiptscreening:run/nigeria-check-batchesThe same check for up to 25 values in one requestscreening:runAPI access starts on the Agency plan. Allowances reset on the 1st of each month; the hourly limit applies per key. GET /usage always tells you what is left.
| Plan | Requests / month | Requests / hour |
|---|---|---|
| Investigator | Not included | — |
| Professional | Not included | — |
| Agency | 100,000 | 1,000 |
| Institutional | Custom | Custom |
Every error returns the same JSON shape with a stable code, a plain message and a request_id to quote to support.
| Code | HTTP | When |
|---|---|---|
AUTHENTICATION_REQUIRED | 401 | No key was sent. |
INVALID_API_KEY | 401 | The key is wrong or has been revoked. |
API_KEY_EXPIRED | 401 | The key has passed its expiry date. |
INSUFFICIENT_SCOPE | 403 | The key does not include the scope the endpoint needs. |
INVESTIGATION_NOT_FOUND | 404 | No investigation with that reference exists in your firm. |
ROUTE_NOT_FOUND | 404 | The endpoint does not exist. |
REPORT_NOT_RELEASED | 409 | The report has not been released yet. |
REQUEST_REJECTED | 409 | The request was understood but cannot be done (the message says why). |
INVALID_JSON | 400 | The request body is not valid JSON. |
VALIDATION_ERROR | 422 | A required field is missing or wrong. |
CAPACITY_EXCEEDED | 429 | The hourly limit or the plan's monthly allowance is used up. |
INTERNAL_ERROR | 500 | Something failed on our side. Quote the request_id to support. |
Every answer also carries X-RateLimit-Limit and X-RateLimit-Remaining headers.
Rather than polling, let us call your system. Add a signed webhook channel in your workspace and choose what it receives: watched-wallet movements, funds reaching an exchange, case watch signals and the daily digest. Each call is an HTTPS POST of JSON with a timestamp and an HMAC-SHA256 signature, so your system can confirm it came from us.
X-ChainTrace-Timestamp: 1762419600 X-ChainTrace-Signature: sha256=<hex HMAC>
Read, submission, report and monitoring rights are granted independently, so an intake form can create cases without ever reading a report.
investigations:create investigations:read reports:read actions:read wallet:assess monitoring:read Need detail for your engineers? Talk to us →
From the Agency plan. Monthly allowances and hourly limits follow your plan, and keys are issued by our team with only the scopes you need.
Once API access is on, your workspace has an API page with every endpoint, its scope, example requests and your usage. Schemas and credentials are shared during onboarding.
No. It returns approved outputs and status. Analyst notes, internal logs, unpublished findings and security settings never leave the workspace.
Yes. With the actions:read scope, a key can read freeze requests, police referrals, Live Pursuit sessions and the custody log for your firm’s cases. It cannot send or change them.
They still work but are deprecated, with a Sunset header for 31 March 2027. Use /investigations and /wallet-assessments instead.
Tell us what enters your systems, what your teams need back and where decisions slow down.