BaseSentinel
M2M threat intelligence for Base (eip155:8453). Pay per call with USDC — no API keys.
Live API: https://api.blackswanlabs.pl Landing: https://blackswanlabs.pl
Detection (what /scan returns)
Dual-source consensus: local bytecode heuristics + GoPlus + honeypot.is buy/sell simulation.
| Field | Values | |-------|--------| | status | SAFE / SUSPICIOUS / SCAM | | verdict | CLEAR / CAUTION / AVOID (agent policy) | | verdict_score | 0–100 (100 = clean) |
Also: risk_flags, reasons, enrichment dossier. Continuous coverage of Uniswap V2/V3, Aerodrome, Clanker, and Virtuals bonding launches (cron + cache).
Sensitivity: trading-gate / mint+gate alone → typically SUSPICIOUS (yellow); gate + blacklist toolkit → SCAM. Empty / EOA → SUSPICIOUS + CAUTION. Minimal/0xef code that still answers ERC-20 (or AccessControl pause/operator) views → STUB_OR_HIDDEN_CODE / ADMIN_POLICY_SURFACE → typically SCAM + AVOID. When GoPlus honeypot_with_same_creator points at a verified ERC-4337 EntryPoint / Base AA bundler → yellow SUSPICIOUS + flag AA_BUNDLER_CREATOR and creator_attribution: "aa_bundler_mislabel" (not hard SCAM — ignore prior-honeypot-on-creator only; still honor honeypot/tax/SCAM on the token itself); real non-AA prior-honeypot creators still → SCAM.
---
How payment works (2 steps)
- Send a USDC Transfer on Base to the treasury wallet (exact product amount).
- Call the endpoint with header:
X-Payment-Proof: 0xYOUR_TX_HASHPay with an on-chain USDC Transfer, then send that transaction hash as X-Payment-Proof. Each proof is bound to one resource and can be redeemed once.
Treasury (Base)
0x21360A04853b85a8d2E918b73f97C8ccf5939946Asset: native USDC on Base — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
---
Products & prices
| Product | Method | Path | Price | |--------|--------|------|-------| | Contract scan | GET | /scan/{address} | 0.005 USDC | | Premium dossier | GET | /dossier/{address} | 0.25 USDC | | Watchdog (7 days) | POST | /watch | 0.50 USDC | | Daily threat feed | GET | /api/feed/daily/YYYY-MM-DD | 0.01 USDC | | Live threat stream | GET | /stream/threats | 0.005 USDC / UTC day |
Machine catalogs:
- https://api.blackswanlabs.pl/.well-known/x402.json
- https://api.blackswanlabs.pl/openapi.json
- https://api.blackswanlabs.pl/tools.json (OpenAI-style tool schemas)
- Human docs: https://api.blackswanlabs.pl/docs
Errors: { "error_code": "...", "message": "...", "error": "..." } — branch on error_code.
Settlement: tx_hash_proof (USDC transfer + hash).
Agent cookbook: https://api.blackswanlabs.pl/docs (402 → pay → retry → branch) Example client: examples/agent-scan.md · npm run example:agent-scan
Discovery is via catalogs (/tools.json, OpenAPI, x402) — not on-chain spam or honeypot traps.
---
Example: scan a contract
1) Pay 0.005 USDC on Base to the treasury
Send exactly 0.005 USDC (or more) to:
0x21360A04853b85a8d2E918b73f97C8ccf5939946
Copy the transaction hash.
2) Call /scan with the proof
PowerShell:
curl.exe -s "https://api.blackswanlabs.pl/scan/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" `
-H "X-Payment-Proof: 0xPASTE_YOUR_TX_HASH_HERE"bash:
curl -s "https://api.blackswanlabs.pl/scan/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
-H "X-Payment-Proof: 0xPASTE_YOUR_TX_HASH_HERE"Without payment you get HTTP 402 with payment_info (amount, payTo, network).
Response includes status (SAFE / SUSPICIOUS / SCAM), agent verdict (CLEAR / CAUTION / AVOID), verdict_score, risk_flags, optional creator_attribution (aa_bundler_mislabel when GoPlus creator is AA infra — not a safe-token signal), and enrichment dossier.
---
Example: premium dossier (0.25 USDC)
curl.exe -s "https://api.blackswanlabs.pl/dossier/0xYourContract" `
-H "X-Payment-Proof: 0xPASTE_YOUR_TX_HASH_HERE"Adds market_structure (deployer %, top-5 holders, LP lock hint, whale flag) on top of /scan. When GoPlus holders are empty, dossier falls back to Transfer logs + live balanceOf.
---
Example: 7-day watch (0.50 USDC)
curl.exe -s -X POST "https://api.blackswanlabs.pl/watch" `
-H "Content-Type: application/json" `
-H "X-Payment-Proof: 0xPASTE_YOUR_TX_HASH_HERE" `
-d '{"target_address":"0xYourContract","webhook_url":"https://your.https.endpoint/hook"}'On verdict / tax / risk_flag changes, BaseSentinel POSTs JSON STATUS_CHANGED to your webhook_url (HTTPS only).
---
Where to find us
Machine catalogs on our host (always current):
- https://api.blackswanlabs.pl/.well-known/x402.json
- https://api.blackswanlabs.pl/openapi.json
- https://api.blackswanlabs.pl/tools.json
- https://api.blackswanlabs.pl/docs
External directories:
| Directory | Status | Notes | |-----------|--------|--------| | Ontario Protocol | Listed | Scan @ 0.005 USDC | | Virtuals ACP | Agent registered | Offerings point at api.blackswanlabs.pl | | x402-list | Submitted — awaiting approval | — |
Agent SDKs (published)
| Package | Install | What it does | |---------|---------|--------------| | MCP | npx -y @basesentinel/mcp / npm i @basesentinel/mcp | Stdio MCP tool scan_contract | | Eliza OS | npm i @basesentinel/eliza | Plugin action SCAN_CONTRACT | | LangChain | pip install basesentinel-langchain | BaseSentinelScanTool for Python agents |
All three SDKs auto-pay 0.005 USDC on Base when the runtime wallet key is set.
| Env | Required | Purpose | |-----|----------|---------| | BASESENTINEL_PRIVATE_KEY | yes | Base wallet with USDC (agent pays per scan) | | BASESENTINEL_RPC_URL | no | Base RPC (default public) | | BASESENTINEL_API_BASE_URL | no | Default https://api.blackswanlabs.pl |
Details and install examples: each package README under packages/.
Listed in the Remote OpenClaw MCP directory
---
License
This repository is licensed under the MIT License (© 2026 BlackSwan Labs). MIT covers the source and SDKs — the live BaseSentinel API remains pay-per-call (USDC); a license does not include free scans.
---
Contact
BlackSwan Labs — https://blackswanlabs.pl blackswanlabsos@gmail.com
