{"openapi":"3.1.0","info":{"title":"DrainBrain API","description":"Solana token rug pull detection. Risk score calibrated on the real outcomes of tokens RugSlayer scanned; honeypot detection, temporal analysis (beta), 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 with DrainBrain. Returns a risk score (0-100, the observed share of tokens with the same profile that died soon after a scan), risk level, rug stage (0-5), honeypot simulation, temporal prediction (beta), 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":"Temporal behavioral prediction (beta; not part of the score). 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 method used. rules=outcome-calibrated rule score (current), heuristic=no feature data available. ensemble / ensemble-temporal appear only on results cached before 2026-10-06.","example":"rules"}}},"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":"rules"}}}},"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. A paid API plan (Builder or Scale) is 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 loaded (they feed the beta temporal output, not the score). 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":"ok","ensemble":"full","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 = the DrainBrain API plan, $199/mo; completing checkout provisions an API key."}}},"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."}}}}