Documentation
What the SybilShield API does, how analyses flow, and how to integrate. The full OpenAPI spec and ready-to-import Postman collection ship with the next release.
How it works
Submit an address list. We ingest on-chain history for every wallet, run six independent detection methods, produce a per-address risk score with evidence, and return both a queryable result set and a downloadable CSV. The whole pipeline takes hours, not weeks.
- 1Register
Create a free account. Receive an API key (shown once — store it securely). Free tier covers 100 calls/month.
- 2Create an analysis
Submit a list of wallet addresses (up to 1M per request) along with chains and sensitivity preference. The platform queues the job and returns an analysis ID.
- 3Track progress
Poll the analysis endpoint or subscribe to a webhook. Status transitions through ingesting → analyzing → scoring → complete.
- 4Read results
Fetch scored addresses (filterable by label), detected clusters, and per-address evidence reports. Export as CSV.
- 5Handle appeals
Flagged users can submit appeals directly via the public endpoint. Every submission is logged immutably and routed to a reviewer.
What you get back
Sybil score
0–100 confidence that the address is part of a Sybil farm. Three bucket labels: genuine, suspicious, sybil.
Cluster ID
Which other wallets in the analysis it groups with, plus the cluster's size and detection method.
Evidence list
Per-address human-readable evidence items pointing at the specific features or cluster memberships that produced the score.
Confidence interval
Calibrated probability output from the ML ensemble alongside per-evidence-item confidence.
CSV export
Full results table for compliance archiving or distribution-list filtering.
Webhook notification
Signed POST to your URL on analysis completion with summary statistics.
Endpoints overview
- Register a new accountReturns an API key shown once
- Rotate API keyInvalidates the old key immediately
- View account & usagePlan, monthly call count, webhook configuration
- Configure webhookSet URL and receive a signing secret
- Create analysisSubmit address list, chains, sensitivity
- List analysesPaginated history of your analyses
- Get analysis statusIncludes summary counts when complete
- Get scored resultsPaginated, filter by label (sybil/suspicious/genuine)
- Export CSVStream the full results table
- Get detected clustersCluster metadata with detection method
- Single-address scoreCached lookup for any address previously seen
- Batch score (up to 100)Bulk lookup endpoint
- Known entity checkCross-analysis intelligence — is this address flagged anywhere?
- Submit feedbackCustomer-side false-positive / false-negative reporting
- Public appealOpen, unauthenticated — anyone can dispute their score
- Appeals policyPublic-readable JSON describing review SLA
Webhook signature verification
Every webhook payload is signed with HMAC-SHA256 using a secret you receive when you configure the webhook URL. The signature arrives in thex-sybilshield-signatureheader as sha256=<hex>. Recompute the HMAC over the raw request body and compare with constant-time equality. Reject mismatches.
Rate limits & quotas
| Plan | Calls / month | Per-minute rate | Concurrent analyses |
|---|---|---|---|
| Free | 100 | 30 / min | 1 |
| Developer | 50,000 | 100 / min | 3 |
| Growth | 250,000 | 300 / min | 10 |
| Enterprise | Unlimited | 1,000 / min | Unlimited |
Exceeding a limit returns HTTP 429 with a retry-after header. We never silently drop data.
Coming next
- · Interactive OpenAPI explorer (Stoplight / Redoc)
- · Ready-to-import Postman collection
- · Official SDKs: TypeScript and Python
- · Streaming results endpoint for >500K-address jobs
- · GraphQL gateway for advanced filtering
Questions? Email hello@sybilshield.com or open an issue on GitHub.