RISK. INVESTIGATIONS. PROTOCOL INTELLIGENCE.Meet your intelligence toolkit ↗
v1REST · JSON · Bearer keys

Forensic intelligence,
one request away.

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.

  • API access from the Agency plan
  • Scoped, revocable keys
  • Only published reports exposed
POST /investigations
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"}'
202 Acceptedillustrative response
{
  "data": { "case_ref": "CT-2048", … },
  "meta": { "request_id": "…", "status_url": "…/investigations/CT-2048/status" }
}
22endpoints in v1
10independent permission scopes
100k+requests a month, from Agency
0unpublished findings exposed

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>

General

Check the service, the networks you can open cases on and what your key has left.

  • GET/healthCheck the API is upno key
  • GET/chainsBlockchains you can open investigations onany key
  • GET/usageThis key's hourly limit and your plan's remaining capacityusage:read

Investigations

Open cases and follow them from tracing to review.

  • GET/investigationsYour firm's 100 most recently updated investigationsinvestigations:read
  • POST/investigationsOpen a new investigation (returns 202 and a status link)investigations:create
  • GET/investigations/{ref}One investigation with its trace summaryinvestigations:read
  • GET/investigations/{ref}/statusTracing jobs and review stateinvestigations:read
  • GET/investigations/{ref}/findingsEvidence-backed findingsinvestigations:read
  • GET/investigations/{ref}/evidence-summaryCounts of evidence files, custody events and findings awaiting reviewinvestigations:read
  • GET/investigations/{ref}/exchange-leadsWhere funds reached exchanges, with attribution and lineage confidenceinvestigations:read
  • GET/investigations/{ref}/relatedOther cases in your firm that share wallets, contacts or wordinginvestigations:read

Reports

Read the report summary once your team has released it.

  • GET/investigations/{ref}/reportReleased report summary (409 until the report is released)reports:read

Recovery actions

Follow freeze requests, police referrals, Live Pursuit and the custody log.

  • GET/investigations/{ref}/freeze-requestsFreeze and preservation requests sent to exchanges, with their statusactions:read
  • GET/investigations/{ref}/law-enforcementPolice and regulator referrals, with reference numbers and follow-upsactions:read
  • GET/investigations/{ref}/pursuitsLive Pursuit sessions and the wallets funds moved toactions:read
  • GET/investigations/{ref}/custodyCustody log entries with their hash chain (newest 200)actions:read

Compliance

Run wallet risk (KYT) and entity (KYB) checks from your own systems.

  • POST/wallet-assessmentsRisk and attribution for one wallet (uses one wallet assessment)wallet:assess
  • POST/entity-profilesProfile of a company or person (uses one entity profile)entity:profile

Monitoring

Manage watched wallets and read their alerts.

  • GET/monitoringMonitored wallets, recent alerts and totalsmonitoring:read
  • POST/monitoringAdd a wallet to monitoring on one of your casesmonitoring:write

Nigeria

  • POST/nigeria-checksNigeria fraud check of one phone, account, name, wallet or website, with a signed receiptscreening:run
  • POST/nigeria-check-batchesThe same check for up to 25 values in one requestscreening:run

Limits by plan

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

PlanRequests / monthRequests / hour
InvestigatorNot included—
ProfessionalNot included—
Agency100,0001,000
InstitutionalCustomCustom

Errors

Every error returns the same JSON shape with a stable code, a plain message and a request_id to quote to support.

CodeHTTPWhen
AUTHENTICATION_REQUIRED401No key was sent.
INVALID_API_KEY401The key is wrong or has been revoked.
API_KEY_EXPIRED401The key has passed its expiry date.
INSUFFICIENT_SCOPE403The key does not include the scope the endpoint needs.
INVESTIGATION_NOT_FOUND404No investigation with that reference exists in your firm.
ROUTE_NOT_FOUND404The endpoint does not exist.
REPORT_NOT_RELEASED409The report has not been released yet.
REQUEST_REJECTED409The request was understood but cannot be done (the message says why).
INVALID_JSON400The request body is not valid JSON.
VALIDATION_ERROR422A required field is missing or wrong.
CAPACITY_EXCEEDED429The hourly limit or the plan's monthly allowance is used up.
INTERNAL_ERROR500Something failed on our side. Quote the request_id to support.

Every answer also carries X-RateLimit-Limit and X-RateLimit-Remaining headers.

Signed webhooks

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>
Least privilege

One key per system.
Only the scopes it needs.

Read, submission, report and monitoring rights are granted independently, so an intake form can create cases without ever reading a report.

Example keyinvestigations:createinvestigations:readreports:readactions:readwallet:assessmonitoring:read
Intake system✓—————
Compliance dashboard—✓——✓✓
Recovery tracker—✓—✓——
Client portal——✓———
Governance

A controlled bridge,
not a back door.

Hashed keysStored and checked by hash; expire or revoke any time.
Firm boundariesEvery query is limited to the authenticated firm’s records.
Publication controlReports stay unavailable until authorised release.
Rate governancePer-key hourly limits keep usage predictable.
Usage recordsTotals, remaining allowance and key details for oversight.
Clear deprecationOld routes carry Deprecation and Sunset headers.
From proof of fit to rollout

Scope around the outcome.

  1. DiscoverWhat enters your systems, and what teams need back.
  2. DesignScopes, events, outputs and boundaries.
  3. ValidateRepresentative cases in a controlled pilot.
  4. Roll outScoped keys, onboarding and support.
Questions

From engineering teams.

Need detail for your engineers? Talk to us →

Is API access included in our plan?

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.

Where is the full documentation?

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.

Can the API see everything in a case?

No. It returns approved outputs and status. Analyst notes, internal logs, unpublished findings and security settings never leave the workspace.

Can we follow recovery work from our own systems?

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.

What happens to the old /cases and /trace routes?

They still work but are deprecated, with a Sunset header for 31 March 2027. Use /investigations and /wallet-assessments instead.

Let’s map your
investigation workflow.

Tell us what enters your systems, what your teams need back and where decisions slow down.