{"openapi":"3.1.0","info":{"title":"DrainBrain API","description":"Solana token rug pull detection powered by a 5-model ML ensemble (XGBoost v1/v2, GRU temporal, NVIDIA NIM, heuristic) trained on 175K+ tokens. Risk scoring, honeypot detection, temporal analysis, wallet clustering. Free tier: 100 scans/day. Agent-friendly: supports API keys, x402 USDC micropayments, and machine commerce endpoints.","version":"1.0.0","contact":{"email":"j@rugslayer.com"},"x-llms-txt":"https://rugslayer.com/llms.txt","x-agent-catalog":"https://rugslayer.com/api/agent/catalog"},"servers":[{"url":"https://rugslayer.com","description":"Production"},{"url":"https://agents.rugslayer.com","description":"Harvey Intel MCP Server (x402 USDC)"}],"paths":{"/api/drainbrain/v1/scan":{"post":{"operationId":"scanToken","summary":"Scan a Solana token for rug pull risk","description":"Analyze a Solana token mint address using a 5-model ML ensemble. Returns a risk score (0-100), risk level, rug stage (0-5), honeypot simulation, temporal prediction, and risk flags. Results are cached for 5 minutes. Free tier returns score/riskLevel/isRug only. Pro/x402 tiers include full breakdown.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mint"],"properties":{"mint":{"type":"string","description":"Solana token mint address in base58 format. Must be 32-44 characters. Get this from any DEX, block explorer, or token listing.","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"action":{"type":"string","enum":["scan_only","quote_if_risky"],"default":"scan_only","description":"scan_only returns risk data. quote_if_risky also returns a Jupiter swap quote if score >= riskThreshold. Pro/x402 only."},"riskThreshold":{"type":"number","default":70,"minimum":0,"maximum":100,"description":"Score threshold to trigger action when action=quote_if_risky."}}},"example":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}}}},"responses":{"200":{"description":"Scan result with risk assessment","content":{"application/json":{"schema":{"type":"object","properties":{"mint":{"type":"string","example":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},"score":{"type":"number","description":"Risk score 0-100. 0=safest, 100=certain rug. Scores >= 70 are considered rugs.","example":12},"riskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"],"description":"LOW (0-30), MEDIUM (31-50), HIGH (51-70), CRITICAL (71-100)","example":"LOW"},"isRug":{"type":"boolean","description":"True if score >= 70","example":false},"cached":{"type":"boolean","description":"True if result came from 5-minute cache","example":false},"timestamp":{"type":"string","format":"date-time"},"rugStage":{"type":"number","description":"Rug lifecycle stage 0-5. 0=Safe, 1=Setup, 2=Pump, 3=Distribution, 4=Preparation, 5=Execution. Pro/x402 only.","example":0},"honeypot":{"type":"object","description":"Jupiter buy/sell simulation result. isHoneypot=true means selling is blocked. Pro/x402 only.","properties":{"isHoneypot":{"type":"boolean","example":false},"reason":{"type":"string","nullable":true,"example":null}}},"riskFlags":{"type":"array","items":{"type":"string"},"description":"Specific risk indicators. Examples: MINT_AUTHORITY_ENABLED, FREEZE_AUTHORITY_ENABLED, LOW_LIQUIDITY, HIGH_HOLDER_CONCENTRATION, LP_UNLOCKED. Pro/x402 only.","example":["MINT_AUTHORITY_ENABLED"]},"temporal":{"type":"object","description":"GRU temporal model prediction. Pro/x402 only.","properties":{"stage":{"type":"number","example":0},"confidence":{"type":"number","example":0.92},"pullHours":{"type":"number","nullable":true,"description":"Estimated hours until rug pull, or null if not detected","example":null}}},"scoreMethod":{"type":"string","description":"Scoring pipeline used. ensemble-nvidia=full 5-model, ensemble=4-model, heuristic=rules only","example":"ensemble-nvidia"}}},"example":{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","score":12,"riskLevel":"LOW","isRug":false,"cached":false,"timestamp":"2026-03-03T16:00:00Z","rugStage":0,"honeypot":{"isHoneypot":false,"reason":null},"riskFlags":["MINT_AUTHORITY_ENABLED"],"temporal":{"stage":0,"confidence":0.92,"pullHours":null},"scoreMethod":"ensemble-nvidia"}}}},"400":{"description":"Invalid input. Check mint format (base58, 32-44 chars). Do NOT retry with same input.","content":{"application/json":{"example":{"error":"Invalid mint address format"}}}},"401":{"description":"Missing or invalid API key. Get a free key: POST /api/drainbrain/v1/keys with {name, email}","content":{"application/json":{"example":{"error":"Invalid API key"}}}},"429":{"description":"Rate limit exceeded. Free: 100/day (resets midnight UTC). Pro: 10K/min. Check X-RateLimit-Remaining header.","content":{"application/json":{"example":{"error":"Daily limit exceeded"}}}},"500":{"description":"Server error. Transient - retry with exponential backoff (1s, 2s, 4s), max 3 retries.","content":{"application/json":{"example":{"error":"Internal server error"}}}}}}},"/api/drainbrain/v1/scan/batch":{"post":{"operationId":"batchScanTokens","summary":"Scan up to 10 tokens in parallel","description":"Batch scan multiple Solana tokens simultaneously. Pro or PAYG tier required. Each token is scanned independently - individual failures don't block the batch.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mints"],"properties":{"mints":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"Array of 1-10 Solana token mint addresses (base58). Each must be 32-44 chars.","example":["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","So11111111111111111111111111111111111111112"]}}},"example":{"mints":["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","So11111111111111111111111111111111111111112"]}}}},"responses":{"200":{"description":"Batch results. Check both results and errors arrays.","content":{"application/json":{"example":{"results":[{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","score":12,"riskLevel":"LOW","isRug":false},{"mint":"So11111111111111111111111111111111111111112","score":5,"riskLevel":"LOW","isRug":false}],"errors":[],"totalMs":245,"count":2}}}},"400":{"description":"More than 10 mints or invalid format"},"401":{"description":"Not authenticated or free tier (batch requires Pro/x402)"}}}},"/api/drainbrain/v1/keys":{"post":{"operationId":"generateApiKey","summary":"Generate a free API key","description":"Create a free DrainBrain API key instantly. No credit card required. 100 scans/day. The key (db_live_xxx) is shown ONLY ONCE in the response - store it securely.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string","description":"Your project or bot name. 1-100 characters.","example":"my-trading-bot"},"email":{"type":"string","format":"email","description":"Contact email for this key.","example":"bot@example.com"}}},"example":{"name":"my-trading-bot","email":"bot@example.com"}}}},"responses":{"201":{"description":"Key generated. SAVE THE apiKey VALUE - it cannot be retrieved later.","content":{"application/json":{"example":{"apiKey":"db_live_abc123def456...","id":"550e8400-e29b-41d4-a716-446655440000","tier":"free"}}}},"429":{"description":"Too many key generation requests. Wait and retry."}}},"get":{"operationId":"listApiKeys","summary":"List all your API keys","description":"List all API keys associated with your email. Requires authentication with any key from that email.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of keys with usage stats","content":{"application/json":{"example":{"keys":[{"id":"uuid","name":"my-bot","tier":"free","calls_today":42,"calls_total":1250,"created_at":"2026-03-01T00:00:00Z","last_used_at":"2026-03-03T16:00:00Z"}]}}}}}}},"/api/drainbrain/v1/keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","description":"Permanently deactivate an API key. Requires authentication with a key from the same email. This action cannot be undone.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID of the key to revoke. Get from GET /api/drainbrain/v1/keys."}],"responses":{"200":{"description":"Key revoked successfully"},"401":{"description":"Unauthorized - key doesn't belong to your email"},"404":{"description":"Key not found"}}}},"/api/drainbrain/v1/keys/{id}/rotate":{"post":{"operationId":"rotateApiKey","summary":"Rotate an API key","description":"Deactivate an existing key and generate a new one with the same tier and email. The new key is shown ONLY ONCE. The old key stops working immediately.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID of the key to rotate."}],"responses":{"200":{"description":"New key generated, old key deactivated","content":{"application/json":{"example":{"apiKey":"db_live_newkey789...","id":"new-uuid","tier":"free"}}}}}}},"/api/drainbrain/v1/health":{"get":{"operationId":"healthCheck","summary":"Check API status and model availability","description":"Returns API operational status and which ML models are available. No authentication required. Use this to verify the API is reachable before making scan requests.","responses":{"200":{"description":"API health status","content":{"application/json":{"example":{"status":"operational","models":{"xgboost_v1":true,"xgboost_v2":true,"gru_temporal":true,"nvidia_nim":true,"heuristic":true},"timestamp":"2026-03-03T16:00:00Z"}}}}}}},"/api/agent/catalog":{"get":{"operationId":"agentCatalog","summary":"Service catalog for agent discovery","description":"Machine-readable catalog of all DrainBrain capabilities, auth methods, and discovery links. No auth required.","responses":{"200":{"description":"Service catalog"}}}},"/api/agent/pricing":{"get":{"operationId":"agentPricing","summary":"Pricing plans and rates","description":"Machine-readable pricing for all tiers including x402 per-call rates. No auth required.","responses":{"200":{"description":"Pricing details"}}}},"/api/agent/policies":{"get":{"operationId":"agentPolicies","summary":"Rate limits, retry policy, and error codes","description":"Machine-readable operational policies. No auth required.","responses":{"200":{"description":"Policy details"}}}},"/api/agent/quote":{"post":{"operationId":"agentQuote","summary":"Generate a priced quote for a plan","description":"Get a quote for a subscription plan. Returns a quote_id to use with /api/agent/checkout. Requires commerce token.","security":[{"commerceAuth":[]}],"requestBody":{"content":{"application/json":{"example":{"plan":"pro","payment_method":"usdc","expected_calls":5000}}}},"responses":{"200":{"description":"Quote with ID and next steps"}}}},"/api/agent/checkout":{"post":{"operationId":"agentCheckout","summary":"Initiate payment for a quoted plan","description":"Start the payment process for a previously quoted plan. Returns payment instructions (Stripe ACP flow or USDC transfer details). Requires commerce token.","security":[{"commerceAuth":[]}],"requestBody":{"content":{"application/json":{"example":{"quote_id":"uuid"}}}},"responses":{"200":{"description":"Payment instructions"}}}},"/api/agent/acp/checkouts":{"post":{"operationId":"acpCreateCheckout","summary":"Create Stripe ACP checkout","description":"Create a checkout for programmatic credit card payment via Stripe Agent Commerce Protocol (ACP). Returns checkout_id and amount_cents. Agent generates a SharedPaymentToken (SPT) for this amount, then provides it via PUT. Requires commerce token.","security":[{"commerceAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["pro"],"description":"Subscription plan. Pro: $29/mo (100 scans/day, AI verdicts)."}}},"example":{"plan":"pro"}}}},"responses":{"201":{"description":"Checkout created. Next: generate SPT for amount_cents, then PUT with token.","content":{"application/json":{"example":{"checkout_id":"uuid","status":"pending_payment_token","amount_cents":2900,"currency":"usd","plan":"pro"}}}}}}},"/api/agent/acp/checkouts/{id}":{"get":{"operationId":"acpGetCheckout","summary":"Check ACP checkout status","security":[{"commerceAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Checkout status, plan, amount, api_key_id if provisioned"}}},"put":{"operationId":"acpProvideToken","summary":"Provide SharedPaymentToken to ACP checkout","description":"Submit the SPT generated by your payment system. Updates checkout to ready_for_completion.","security":[{"commerceAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shared_payment_granted_token"],"properties":{"shared_payment_granted_token":{"type":"string","description":"Stripe SharedPaymentToken (starts with spt_)"}}},"example":{"shared_payment_granted_token":"spt_..."}}}},"responses":{"200":{"description":"Token accepted, status updated to ready_for_completion"},"409":{"description":"Checkout not in pending_payment_token status or expired"}}}},"/api/agent/acp/checkouts/{id}/complete":{"post":{"operationId":"acpCompleteCheckout","summary":"Execute ACP payment and provision API key","description":"Charges the SPT via Stripe PaymentIntent and provisions a DrainBrain API key. The raw API key is returned ONLY in this response - store it securely.","security":[{"commerceAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment succeeded, API key provisioned","content":{"application/json":{"example":{"checkout_id":"uuid","status":"provisioned","api_key":"db_live_xxx...","tier":"pro"}}}},"402":{"description":"Payment declined by Stripe"},"409":{"description":"Checkout not in ready_for_completion status"}}}},"/api/agent/acp/checkouts/{id}/cancel":{"post":{"operationId":"acpCancelCheckout","summary":"Cancel an ACP checkout","description":"Cancel a checkout that has not yet been completed. Only works for pending_payment_token or ready_for_completion statuses.","security":[{"commerceAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Checkout cancelled"},"409":{"description":"Checkout cannot be cancelled in its current status"}}}},"/api/agent/checkout/{id}":{"get":{"operationId":"agentCheckoutStatus","summary":"Check checkout status","security":[{"commerceAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout status and timeline"}}}},"/api/agent/subscription":{"get":{"operationId":"agentSubscription","summary":"Get active subscription status","security":[{"commerceAuth":[]}],"responses":{"200":{"description":"Active tier, payment method, start date"}}}},"/api/agent/usage":{"get":{"operationId":"agentUsage","summary":"Get API usage statistics","security":[{"commerceAuth":[]}],"responses":{"200":{"description":"Call counts, daily limits, remaining quota"}}}},"/api/agent/invoices":{"get":{"operationId":"agentInvoices","summary":"Get invoice history","security":[{"commerceAuth":[]}],"responses":{"200":{"description":"List of paid/provisioned checkouts"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"DrainBrain API key. Format: db_live_xxx. Get a free key: POST /api/drainbrain/v1/keys with {name, email}. Free tier: 100 scans/day."},"commerceAuth":{"type":"http","scheme":"bearer","description":"Agent commerce token for quote/checkout/subscription/usage endpoints. Contact j@rugslayer.com for access."}}}}