API reference
Every endpoint, exactly as deployed.
Plain HTTP + JSON. Public checks need no key. Partner routes use sandbox or production Bearer keys — and fail closed when protection can’t be verified.
api.antivamp.io
Production · av_live_…
sandbox-api.antivamp.io
Sandbox · av_sbx_…
antivamp.io/api
This reference + OpenAPI
Decisions
Five outcomes. Zero ambiguity.
Prefer enforceLaunch() in the SDK — it verifies Ed25519 signatures and never treats “not block” as allow.
allow
Clear to launch
allow_authorized_only
Only the authorized wallet
block
Reject — protected identity
recheck_required
Retry — do not launch
service_unavailable
Fail closed
Endpoints
Surface area
Production /events/* also needs X-AntiVamp-Keeper: Bearer …. Sandbox event reports skip the keeper.
Public identity
No API key. Perfect for checkers, badges, and explorer UIs.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| GET/POST | /api/v1/identity/check | None | live | Check a name + ticker. Optional chain & launcher. Returns status, decision, authorized launcher, expiry, source. |
| GET | /api/v1/identity/status?key=NAME::TICKER | None | live | Identity detail + full event timeline by identity key. |
| GET | /api/v1/protected-identities | None | live | Explorer list. Default status=active (reserved|protected|blocked), production only. Filters: q / chain / status / cursor (max 50). |
| GET | /api/v1/reservations?wallet=… | None | live | Reservations for a launcher wallet. wallet required: hex or base58 alphanumeric (3–64). Wildcards rejected — full dumps are not public. |
| GET | /api/badge | None | live | Embeddable Protected-by-AntiVamp badge (SVG or JSON). |
Signed decisions
Ed25519 validation — verify with public keys from /v1/keys.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| POST | /api/v1/launches/validate | Bearer key | live | Signed launch decision (5-min TTL). Idempotency-Key + nonce. 503 if signing unavailable. |
| GET | /api/v1/keys | None | live | Public Ed25519 keys for verifying decisions (+ rotation overlap). |
| POST | /api/v1/decisions/verify | None | live | Server-side signature + freshness check. Prefer local SDK verify in production. |
Launch lifecycle
Report launches and protection events. Production events need a keeper header.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| POST | /api/v1/launches/report | Bearer key | live | Report a completed launch into the shared index (launch:report scope). |
| POST | /api/v1/events/bonded | Bearer + keeper* | live | Bond lock: 60d reserved / 48h unreserved. Production requires X-AntiVamp-Keeper. |
| POST | /api/v1/events/milestone | Bearer + keeper* | live | ~$1M MC lock: 90d reserved / 7d unreserved. Production requires keeper. |
| POST | /api/v1/reservations | Bearer key | sandbox | Seed a sandbox reservation for lifecycle tests. Production holds are on-chain only. |
| GET | /api/v1/reservations/quote | Bearer + reservation:prepare | live | Preview tier + on-chain quote (same oracle as prepare). Fail closed if stale. |
| POST | /api/v1/reservations/prepare | Bearer + reservation:prepare | live | Prepare reserve tx + revenueShare snapshot. Sandbox always simulated (non-payable); production is creator-signable on-chain. Attribution from API key. Optional payer (Solana) splits fee payer from launcher — launcher co-signs via launcherApproval. |
| POST | /api/v1/reservations/delegate-launcher | Bearer or keyless (holder signature) | live | Authorize one extra launch wallet on an active hold — the current on-chain holder signs a canonical message. Rescues holds paid by a wallet that cannot launch. Self-serve at /reservations. |
| POST | /api/v1/reservations/sandbox-confirm | Bearer + reservation:prepare | sandbox | Force-confirm a simulated sandbox prepare — seeds identity + accrues ledger without mainnet spend. Payouts stay gated. |
| GET/POST | /api/v1/reservations/status | Bearer + reservation:prepare | live | Poll prep status / report tx hash. Confirmed only after on-chain reconcile (or sandbox-confirm). |
| IFRAME | /embed/reserve?launchpad=… | Origin allowlist | live | Hosted partner Reserve widget (+ /embed/reserve.js helper). Theme + accent customizable per partner profile. |
| POST | /api/v1/launch/pumpfun/metadata | Public (IP rate limited) | live | Pin launch image + pump.fun-style metadata JSON to IPFS for /launch. 503 until the launch factory is enabled. |
| POST | /api/v1/launch/pumpfun/prepare | Public (IP rate limited) | live | AntiVamp-native pump.fun launch: identity gate first, then official create_v2 (+ optional ≤10 SOL initial buy). Free launch; immutable 70/30 creator-fee share. |
| POST | /api/v1/launch/pumpfun/fee-share | Public (IP rate limited) | live | Fresh-blockhash fee-share tx after create confirms; retry path for reconciliation_pending. |
| POST | /api/v1/launch/pumpfun/confirm | Public (IP rate limited) | live | Confirm launch against on-chain state and index the identity. Mint alone never locks a ticker — bond/milestone locks do. |
Partner revenue
Accrued launchpad share after on-chain confirmation. Production payouts stay gated off.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| GET | /api/v1/partner/profile | Bearer + partner:revenue | live | Split (bps), payout wallets, same-chain routing policy. |
| GET | /api/v1/partner/revenue | Bearer + partner:revenue | live | Ledger summary + entries. Accrued ≠ paid. |
| GET | /api/v1/partner/reservations | Bearer + partner:revenue | live | Attributed reservations with ledger status. |
| POST | /api/v1/partner/reservations/sync | Bearer + partner:revenue | live | Reconcile pending prepares on-chain, accrue ledger, power Revenue Sync. |
| GET | /api/v1/partner/revenue/reconcile | Bearer + partner:revenue | live | Soft prepare↔ledger consistency check (read-only). |
| GET | /api/v1/partner/payout-batches | Bearer + partner:revenue | live | Daily 24h payout plans/queues (read-only). |
| POST | /api/v1/partner/payout-wallets/verify/challenge | Bearer + partner:payout | live | Start Solana/EVM ownership challenge. |
| POST | /api/v1/partner/payout-wallets/verify | Bearer + partner:payout | live | Complete wallet verification. |
| POST | /api/v1/partner/payout-wallets/rotate | Bearer + partner:payout | live | Archive verified wallet and challenge a new address. |
Solana reserve helpers
Build and confirm real on-chain Solana reservations.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| GET | /api/v1/solana/quote | None | live | SOL quote for a tier + oracle freshness (fail closed if stale). |
| GET | /api/v1/solana/reserve-context | None | live | PDAs, treasury, blockhash, oracle context for reserve txs. |
| GET | /api/v1/solana/blockhash | None | live | Fresh Solana recent blockhash. |
| POST | /api/v1/solana/send | None | live | Broadcast a signed Solana transaction via server RPC. |
| GET | /api/v1/solana/tx-status | None | live | Transaction confirmation by signature. |
Sandbox & metering
Self-serve keys, logs, and usage for partners.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| POST | /api/v1/sandbox/keys | None | live | Create a sandbox key. Raw key + webhook secret shown once. |
| GET/DELETE | /api/v1/sandbox/keys | Bearer key | live | Introspect or revoke the calling key. |
| GET | /api/v1/sandbox/logs | Bearer key | live | Recent request logs for the calling key. |
| GET | /api/v1/sandbox/usage | Bearer key | live | Usage aggregation: volume, errors, latency, by endpoint/chain/decision. |
Webhooks
HMAC-signed deliveries with history and replay.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| GET/POST | /api/v1/webhooks | Bearer key | live | List or register endpoints. HTTPS only; private/metadata IPs rejected. X-AntiVamp-Signature (HMAC-SHA256). |
| PATCH/DELETE | /api/v1/webhooks/:id | Bearer key | live | Pause, rotate secret, or delete. |
| GET | /api/v1/webhooks/deliveries | Bearer key | live | Delivery history with attempts and status codes. |
| POST | /api/v1/webhooks/deliveries/:id/replay | Bearer key | live | Replay a recorded delivery. |
| POST | /api/v1/webhooks/test | Bearer key | live | Send a signed test event to active endpoints. |
Platform
Health, chains, disputes, and the machine-readable spec.
| Method | Path | Auth | Status | Description |
|---|---|---|---|---|
| GET | /api/v1/chains | None | live | Typed chain registry + live health probes. |
| GET | /api/v1/health | None | live | Index, HyperEVM RPC, Solana oracle, indexers, partner API. |
| POST/GET | /api/v1/disputes | None | live | Submit or read disputes (EVM wallet-proof). Guardian-reviewed. |
| GET | /api/v1/openapi | None | live | OpenAPI 3.1 JSON for this API. |
Errors
Structured codes, always
Shape: { error: { code, message, details? } }. Treat any validation 5xx as a blocked launch.
| Code | HTTP | Meaning |
|---|---|---|
| invalid_json | 400 | Body was not valid JSON. |
| invalid_request | 400 | Schema validation failed — details included. |
| wallet_required | 400 | GET /reservations requires ?wallet=… |
| invalid_wallet | 400 | wallet must be hex/base58 alphanumeric (3–64); no wildcards. |
| insecure_url | 400 | Webhook URL must be https and must not target private or metadata IPs. |
| missing_api_key | 401 | No Authorization: Bearer header. |
| invalid_api_key | 401 | Key unknown or malformed. |
| key_revoked | 401 | Key has been revoked. |
| wrong_environment | 403 | Sandbox key on api.antivamp.io (or live key on sandbox-api). antivamp.io console accepts both. |
| insufficient_scope | 403 | Key lacks the required scope. |
| keeper_required | 403 | Production event missing X-AntiVamp-Keeper. |
| production_reporting_restricted | 403 | Sandbox keys cannot seed production reservations. |
| webhook_not_found | 404 | Webhook id not found for this key. |
| delivery_not_found | 404 | Delivery id not found for this key. |
| rate_limited | 429 | Per-key or public per-IP limit exceeded. |
| validation_failed | 502 | Backend unavailable — fail closed. |
| service_unavailable | 503 | Not configured, or chain validation paused. |
| signing_unavailable | 503 | Decision signing key missing — fail closed. |
| keeper_unconfigured | 503 | Production events need ANTIVAMP_KEEPER_TOKENS. |