# AlgoSentry

AlgoSentry is a per-call API service that checks Algorand Standard Assets (ASAs) for fraud indicators
and reports live Algorand network health. It is designed for machine-to-machine consumption and is
paid via the x402 protocol using USDC or ALGO on Algorand.

## What AlgoSentry does

GET /v1/asa/registry-check?asset_id=<INTEGER> — given an Algorand ASA ID, returns:
- A verdict: "ok", "warning", or "high_risk"
- A safety score from 0 (most dangerous) to 100 (safest)
- A list of flags explaining the verdict (clawback enabled, name similarity to known assets, etc.)
- Holder distribution data (concentration risk)
- Creator account information (account age, number of assets created)
- Similarity matches against a list of known legitimate assets

GET /v1/network/pulse — returns a live Algorand network snapshot: current round, estimated
transactions-per-second over a recent block window, average block time, and the current
minimum transaction fee. No parameters required.

POST /v1/contract/audit — given TEAL or Puya (Algorand Python) smart contract source code in
the request body ({"source": "<code>", "language": "teal"|"puya" (optional)}), returns a
security audit: verdict, 0-100 score, and structured findings (missing authorization checks,
rekey abuse, unchecked transaction group assumptions, unvalidated close-to fields, integer
overflow, and more). Powered by Claude (claude-opus-4-8). Price scales with
submitted code size and current AI inference cost.

## How to use AlgoSentry

AlgoSentry uses the x402 HTTP payment protocol. Follow these steps:

Step 1: Send a GET request to /v1/asa/registry-check?asset_id=<INTEGER> without any payment header.
Step 2: The server responds with HTTP 402 and a JSON body containing payment instructions (payTo address, price, accepted assets).
Step 3: Send an on-chain Algorand transaction: 20000 microUSDC (0.02 USDC, ASA 10458941) or 50000 microALGO (0.05 ALGO) to the payTo address.
Step 4: Retry your GET request with the header: X-PAYMENT: <base64_encoded_payment_proof>
  The payment proof is base64-encoded JSON: {"x402Version":1,"scheme":"exact","network":"algorand-testnet","payload":{"txid":"<TXID>","asset":"<ASSET_ID>"}}
Step 5: Receive a 200 JSON response with the analysis.

## Key behaviors

- Idempotency: Include an Idempotency-Key header to safely retry on timeout without double payment.
- Credit: If the server fails after payment, you receive a credit_nonce in the error response. Use it in the X-Credit-Nonce header on your next attempt.
- Caching: Responses are cached for 30 minutes. Cached responses are marked with "cached": true. Payment is still required for cached responses.
- Coercion: asset_id is automatically coerced from string to integer if possible. Coercion warnings appear in the "warnings" field.

## Pricing

/v1/asa/registry-check:
- 0.02 USDC (ASA 10458941, 20000 micro-units) per call — preferred
- 0.05 ALGO (native, 50000 micro-units) per call — fallback

/v1/network/pulse:
- 0.01 USDC (ASA 10458941, 10000 micro-units) per call — preferred
- 0.025 ALGO (native, 25000 micro-units) per call — fallback

/v1/contract/audit (scales with submitted source size AND current AI inference cost, up to 60000 characters):
- small contract (<= 4000 chars): ~0.21 USDC or 0.53 ALGO
- medium contract (<= 16000 chars): ~0.47 USDC or 1.18 ALGO
- large contract: ~1.00 USDC or 2.50 ALGO
These are illustrative examples only — the exact price for your specific submission is always returned in the 402 response, and may change if the underlying AI model or its pricing changes.

## Free endpoints

- GET /v1/ping-sample — Returns a real example response for USDC (ASA 31566704). No payment needed. Use this to validate your integration.
- GET /healthz — Service liveness check.

## Response schema

The full OpenAPI 3.1 schema is available at: https://www.algosentry.cloud/openapi.json

Key response fields:
- asset_id (integer): The queried ASA ID
- verdict (string): "ok" | "warning" | "high_risk"
- score (integer 0-100): Safety score, higher is safer
- flags (array): Each flag has {code, severity, description}
- asset.clawback_enabled (boolean): True if creator can claw back tokens
- asset.freeze_enabled (boolean): True if creator can freeze transfers
- asset.creator.account_age_days (integer): Age of creator account in days
- holder_distribution.top_1_pct (float): % of supply held by top holder
- similarity_matches (array): Similar known assets (potential impersonation)
- payment_receipt (object): Proof of payment included in each 200 response
- cached (boolean): True if response was served from cache
- warnings (array): Non-blocking issues (e.g. type coercion)

## Network

AlgoSentry operates on algorand-testnet. Algorand transactions confirm in approximately 3-4 seconds.

## Contact

Service URL: https://www.algosentry.cloud
API reference: https://www.algosentry.cloud/openapi.json
x402 manifest: https://www.algosentry.cloud/.well-known/x402.json