ASA Sentinel API

Start here

A report checks who controls an ASA — its manager, freeze, clawback and reserve rights — plus recent authority changes, rekey status on those control addresses, and how much of the holder set could actually be confirmed. It returns a risk level (LOW, MEDIUM, HIGH or UNKNOWN) with evidence for every finding.

Each deployment serves a single Algorand network. Don't assume mainnet — read network_name from GET /v1/config/public before integrating. The same endpoint returns the current USDC asset id and the exact price this deployment charges per report.

200 OK
{
  "network": "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
  "network_name": "testnet",
  "algod_url": "https://testnet-api.algonode.cloud",
  "usdc_asset_id": 10458941,
  "price_usdc": "0.01"
}

ASA Sentinel never holds your funds or your keys. You sign the payment yourself, from your own wallet — the server only ever receives a signed transaction (or a gateway-specific proof) to verify and settle.

Request flow

A direct 200 from POST /v1/reports happens only when you resubmit a proof for a payment that has already completed — the same report is returned again rather than being regenerated.

API reference

POST /v1/reports

Request body:

Responses:

{
  "error": "payment required",
  "challenge": {
    "priceUsdc": "0.01",
    "usdcAssetId": 10458941,
    "payTo": "<pay-to-address>",
    "nonce": "<challenge-nonce>",
    "expiresAt": "2026-07-24T12:05:00.000Z"
  }
}

{
  "payment_id": "<uuid>",
  "status": "report_queued",
  "status_url": "/v1/payments/<uuid>",
  "retrieval_token": "<retrieval-token>",
  "retry_after_seconds": 3
}

GET /v1/reports/:id

:id is the payment_id, not a separate report id — no report row exists until generation completes. Pass the retrieval token as ?token= or an X-Retrieval-Token header.

GET /v1/payments/:id

Same authentication, a lighter status-only envelope — useful for polling without re-fetching the full report body: payment_id, status, report_id, failure_code, detail, retry_after_seconds.

Retrieval tokens

The retrieval token is signed and scoped to one payment and one payer wallet — it can't be reused for a different payment or forged for a different buyer. Treat it like a bearer credential for that one report: don't log it, and don't share a report link that contains it with anyone you don't want to see that report.

Report contents

Fields on the completed report object:

{
  "assetId": 10458941,
  "riskLevel": "HIGH",
  "controlRights": {
    "clawback": { "address": "CLAWBACKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" },
    "defaultFrozen": false,
    "roleOverlaps": false
  },
  "holderDistribution": { "holdersScanned": 842, "creatorSharePct": 18.4, "dataIncomplete": false },
  "findings": [
    {
      "ruleId": "unknown-clawback-authority",
      "severity": "high",
      "explanation": "Asset has an active clawback authority with no known association.",
      "evidence": { "address": "CLAWBACKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  ],
  "rulesetVersion": "2026-07-23.3"
}

Failure and retry behavior

Submitting the exact same X-Payment-Proof again is safe: it returns the current state of that payment instead of re-settling or rebuilding the report.

Report generation is retried automatically a few times before a payment is marked terminal. Until then, requests return 202. Once terminal, both status endpoints return 402 with one of these codes:

A terminal payment is not automatically retried further — contact support with the payment id.

Method and limits

The full ruleset — what each risk level means, how known-address labels work, and how incomplete holder data is handled — is documented in plain language on the methodology page.

• Known-address labels are curated associations, never endorsements.
• Incomplete holder data is stated explicitly, not silently rounded up.
• UNKNOWN means the ruleset couldn't reach a conclusion — it is not the same as LOW.
• Nothing in a report is investment advice.