ASA Sentinel API

Start here

A report answers one question: what can this asset's issuer still do to the people holding it, and which of those powers has it permanently given up? The primary field is capabilitySummary — a plain statement for configuration control, freeze, clawback, reserve and supply, each with a durability state and the on-chain evidence behind it.

On Algorand a control address that has been cleared can never be reinstated, and clearing the manager address locks the whole configuration permanently. So the report separates a power the issuer happens not to be using from one it can never use again.

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": 137594422,
  "capabilitySummary": {
    "configurationMutable": true,
    "permanentlyRenounced": ["freeze", "clawback"],
    "statements": [
      {
        "capability": "configuration",
        "state": "active",
        "statement": "Configuration can still be changed. An active manager address can reassign the reserve and manager addresses.",
        "holderEffect": "The manager can reassign the reserve and manager addresses at any time, so the configuration shown below can still change. The freeze and clawback addresses are already cleared, and Algorand provides no way to reinstate a cleared control address, so the manager cannot restore those powers. The manager cannot change total supply or decimals.",
        "address": { "address": "<manager-address>" },
        "evidenceTier": "verified_on_chain_fact",
        "basis": { "checkedRound": 63430401 }
      },
      {
        "capability": "clawback",
        "state": "permanently_renounced",
        "statement": "No holding of this asset can ever be clawed back. The address is cleared, and Algorand provides no way to reinstate a cleared control address for the life of an asset. It was cleared at round 12853636.",
        "evidenceTier": "derived_deterministic",
        "basis": {
          "checkedRound": 63430401,
          "renouncedAtRound": 12853636,
          "renouncedTxId": "<txid>"
        }
      },
      {
        "capability": "supply",
        "state": "fixed_at_creation",
        "statement": "Total supply is fixed. An ASA's total and decimals are set once at creation and cannot be altered afterwards, so the manager cannot mint additional units.",
        "evidenceTier": "derived_deterministic",
        "basis": { "checkedRound": 63430401 }
      }
    ]
  },
  "lifecycle": { "status": "active", "createdAtRound": 12263663 },
  "controlRights": {
    "manager": { "address": "<manager-address>" },
    "reserve": { "address": "<reserve-address>" },
    "defaultFrozen": false,
    "roleOverlaps": true
  },
  "configChangeScanWindow": {
    "fromRound": 12263663,
    "toRound": 63430401,
    "creationReached": true,
    "scanLimitReached": false,
    "eventsScanned": 2,
    "configChangesObserved": 1,
    "incomplete": false
  },
  "findings": [
    {
      "ruleId": "recent-critical-config-change",
      "severity": "high",
      "evidenceTier": "derived_deterministic",
      "explanation": "Control rights freeze, clawback changed at round 12853636.",
      "evidence": { "txId": "<txid>", "round": 12853636, "changedRoles": ["freeze", "clawback"] }
    }
  ],
  "freshness": {
    "computedAt": "2026-07-25T09:44:00.000Z",
    "checkedRound": 63430401,
    "servedFromCache": false
  },
  "riskLevel": "UNKNOWN",
  "rulesetVersion": "2026-07-25.2",
  "rulesetChangelogUrl": "https://asasentinel.com/methodology#ruleset-changelog"
}

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 method — what each capability state means, the four evidence tiers, how history coverage is established, and how known-address labels work — is documented in plain language on the methodology page.

• Every claim carries an evidenceTier: verified_on_chain_fact, derived_deterministic, known_association, or unknown_or_incomplete.
• Configuration history is scanned back to the asset's creation. creationReached says whether it got there; a bounded scan is never described as complete.
• An incomplete scan does not weaken a permanence statement — those rest on the asset's configuration at the checked round plus a protocol rule, not on history. What it costs is the ability to say when a power was given up.
• Known-address labels are curated associations, never endorsements.
• Holder distribution is not reported. A complete holder set cannot be retrieved inside a request budget, and a capped sample supports neither an honest holder count nor a creator share.
• ASA Sentinel does not determine whether an asset is safe, legitimate, approved, or a good investment. It reports what the issuer can technically do.
• Nothing in a report is investment advice.