Aicscan Documentation
FrançaisEnglish

Quickstart

This guide takes you from account creation to your first alert, in about ten minutes. The examples use curl; every endpoint of the reference also shows the JavaScript and Python equivalent.

1. Create an account and a workspace#

Sign up at aicscan.io/app/inscription, confirm your email address, then create your workspace: it holds your addresses, rules, channels and API keys. Each API key belongs to a single workspace and only sees its data.

The public API is included in the Pro and Business plans. On the Free and Starter plans, every authenticated call answers 403 plan_required. See Plans and quotas.

2. Get an API key#

In the client area, open the API keys page (owner or administrator of the workspace) and click “Create key” after choosing:

  • a name saying where the key is used;
  • the scope: read (read only) or read and write (read and modify);
  • if needed, an expiry (30 to 365 days).

See Authentication for the creation and revocation rules. For a key with its own rate limit, write to support@aicscan.io.

The full key, shaped like aic_k3J9xQ2a_…, is shown only once: Aicscan only keeps its SHA-256 hash. Store it in a secrets manager, never in source code, a mobile app or a browser.

Shell
export AICSCAN_API_KEY="aic_k3J9xQ2a_..."

3. Make your first call#

GET /v1/workspace returns the key's workspace, its plan, its limits and today's usage. It is the best call to check that a key works.

Shell
curl https://aicscan.io/v1/workspace \
  -H "Authorization: Bearer $AICSCAN_API_KEY"
JSON
{
  "workspace": { "id": "0193a1b2-0c1d-7e4f-8a9b-1c2d3e4f5a01", "name": "Acme Treasury", "plan": "pro", "state": "active", "created_at": "2026-10-02T08:00:00Z" },
  "plan": { "code": "pro", "name": "Pro" },
  "limits": { "addresses": 100, "rules": null, "channels": 10, "channel_kinds": null, "chains": null, "requests_per_second": 25, "requests_per_day": 10000, "immediate_alert": true },
  "usage": { "addresses": 12, "rules": 4, "channels": 3, "requests_today": 318 },
  "api_key": { "id": "0193a1a0-77b1-7c3d-8e9f-0a1b2c3d4e5f", "prefix": "aic_k3J9xQ2a", "scopes": ["read", "write"] }
}

A null limit means unlimited. Every response also carries the rate limit headers (RateLimit-*) and, on the Pro plan, the daily quota headers.

4. Create a delivery channel#

A rule sends its alerts to one or more channels. Let’s create a webhook: Aicscan will send every alert as a JSON POST to your HTTPS server.

Shell
curl -X POST https://aicscan.io/v1/channels \
  -H "Authorization: Bearer $AICSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"webhook","url":"https://hooks.example.com/aicscan","name":"SIEM","locale":"en"}'

The 201 response contains the channel id and, only once, its signing secret webhook_secret (whsec_…). Keep it: you need it to verify signatures.

Prefer Telegram, helloMe, Discord, Slack or email? See Channels.

5. Watch an address#

Shell
curl -X POST https://aicscan.io/v1/addresses \
  -H "Authorization: Bearer $AICSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"chain_id":56,"address":"0x8894E0a0c962CB723c1976a4421c95949bE2D4E3","label":"Treasury"}'

The address is validated (EIP-55 checksum when it is mixed case, base58 T… accepted on TRON), then returned lowercase in address and in display form in display_address. Chain ids are listed in Chains and assets.

This step is optional: a rule adds its addresses to the watched addresses by itself.

6. Create a rule#

Alert as soon as an outflow of at least 50,000 USDT leaves the address on BNB Chain:

Shell
curl -X POST https://aicscan.io/v1/rules \
  -H "Authorization: Bearer $AICSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Treasury: large USDT outflows",
    "kind": "large_transfer",
    "chain_id": 56,
    "addresses": ["0x8894e0a0c962cb723c1976a4421c95949be2d4e3"],
    "asset": "0x55d398326f99059ff775485246999027b3197955",
    "threshold": "50000",
    "direction": "outgoing",
    "severity": "critical",
    "channel_ids": ["<id of the channel created in step 4>"]
  }'

The threshold is written in token units ("50000", "0.5"); Aicscan converts it with the token's decimals. A critical rule sends a first alert as soon as the transaction is seen, before confirmations, then a second one at confirmation. The other rule types are described in Rule types.

7. Send a test message#

Shell
curl -X POST https://aicscan.io/v1/channels/$CHANNEL_ID/test \
  -H "Authorization: Bearer $AICSCAN_API_KEY"

The 202 response returns notification_id; follow the delivery with GET /v1/notifications/{id}, which also lists the attempts (delivery_attempts) with the HTTP status returned by your server.

8. Receive an alert#

When a transfer matches the rule, your server receives:

HTTP
POST /aicscan HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: Aicscan-Webhook/1
X-Event-Id: 0193a1c9-41aa-7b2e-9c0d-1e2f3a4b5c6d
X-Timestamp: 1794648613
X-Signature: sha256=5d0f4c…
JSON
{
  "id": "0193a1c9-41aa-7b2e-9c0d-1e2f3a4b5c6d",
  "type": "alert",
  "stage": "unconfirmed",
  "severity": "critical",
  "priority": 30,
  "attempt": 1,
  "timestamp": 1794648613,
  "title": "🔴 CRITICAL · Treasury: large USDT outflows · outgoing",
  "text": "🔴 CRITICAL · Treasury: large USDT outflows · outgoing\n⏳ UNCONFIRMED · waiting for 15 confirmations\nChain: BNB Chain\n…"
}

Verify the signature, answer 2xx within 10 seconds, and you are done. The Webhooks guide gives complete receivers in Node.js, Python, PHP and Go.

Without a public server, you can also read alerts with GET /v1/matches or receive them live on the real-time stream.

Next steps#