{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Pump Intelligence Developer API","version":"1.0.0","description":"Shared read-only data and research gateway for AskPumpGPT and independent applications. Requires individual developer keys and confirmed redistribution rights. Commercial billing and future subscriptions are inactive. Observed warehouse data can be delayed or incomplete. No direct SQL, unrestricted exports, real-time guarantees or trade execution. Data service queries: 8s compute cap, 20s gateway deadline, two concurrent data leases; research: 240s deadline, one job/account and three global. Requests: 8 KiB body, 2,048-character URL; metered response: 256 KiB. Failed data work refunds credits; ambiguous research outcomes retain the debit and cannot be retried with the same identity. Use research history to reconcile before submitting a new identity."},"servers":[{"url":"/","description":"Same API origin; works with the website or independent headless gateway."}],"paths":{"/v1/tokens":{"get":{"operationId":"listTokens","summary":"Observed token aggregates with stable tie ordering within a warehouse release.","security":[{"developerKey":[]}],"x-required-scope":"tokens:read","x-credit-cost":1,"parameters":[{"name":"limit","in":"query","description":"Maximum returned rows.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Bounded offset. Compare dataVersion across pages.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"q","in":"query","description":"Case-insensitive warehouse mint, symbol or name search; no external enrichment.","required":false,"schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"date","in":"query","description":"UTC creation date.","required":false,"schema":{"type":"string","format":"date"}},{"name":"graduated","in":"query","description":"Observed graduation filter.","required":false,"schema":{"type":"boolean"}},{"name":"sort","in":"query","description":"Descending source-allowlisted sort field.","required":false,"schema":{"type":"string","enum":["create_ms","ath_mc_q","n_trades","unique_buyers","volume_q"],"default":"create_ms"}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 1 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataPage"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tokens/{mint}":{"get":{"operationId":"getToken","summary":"One observed token aggregate. Does not return trade history or live enrichment.","security":[{"developerKey":[]}],"x-required-scope":"tokens:read","x-credit-cost":1,"parameters":[{"name":"mint","in":"path","description":"Observed Solana base58 address.","required":true,"schema":{"type":"string","pattern":"^[1-9A-HJ-NP-Za-km-z]{32,44}$"}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 1 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEntity"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/wallets/{address}":{"get":{"operationId":"getWallet","summary":"Observed wallet aggregate, including explicitly labeled source estimates.","security":[{"developerKey":[]}],"x-required-scope":"wallets:read","x-credit-cost":3,"parameters":[{"name":"address","in":"path","description":"Observed Solana base58 address.","required":true,"schema":{"type":"string","pattern":"^[1-9A-HJ-NP-Za-km-z]{32,44}$"}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 3 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEntity"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/creators/{address}":{"get":{"operationId":"getCreator","summary":"Observed creator launch and quote-unit aggregates.","security":[{"developerKey":[]}],"x-required-scope":"creators:read","x-credit-cost":3,"parameters":[{"name":"address","in":"path","description":"Observed Solana base58 address.","required":true,"schema":{"type":"string","pattern":"^[1-9A-HJ-NP-Za-km-z]{32,44}$"}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 3 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataEntity"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/transactions":{"get":{"operationId":"transactionsUnavailable","summary":"Reserved contract: standalone transaction feed unavailable; returns 501 without a credit debit.","security":[{"developerKey":[]}],"x-required-scope":"transactions:read","x-credit-cost":0,"parameters":[{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"401":{"description":"Developer authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"transactions:read scope required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"No verified independently bounded transaction feed connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Application authentication store unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics":{"get":{"operationId":"getAnalytics","summary":"Bounded hourly observed market aggregates.","security":[{"developerKey":[]}],"x-required-scope":"analytics:read","x-credit-cost":5,"parameters":[{"name":"limit","in":"query","description":"Maximum returned rows.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Maximum offset 168.","required":false,"schema":{"type":"integer","minimum":0,"maximum":168,"default":0}},{"name":"hours","in":"query","description":"Lookback window ending at current UTC time.","required":false,"schema":{"type":"integer","minimum":1,"maximum":168,"default":24}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 5 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataPage"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/historical":{"get":{"operationId":"getHistorical","summary":"Observed market aggregates or capture coverage, at most 31 inclusive UTC dates per query.","security":[{"developerKey":[]}],"x-required-scope":"historical:read","x-credit-cost":5,"parameters":[{"name":"limit","in":"query","description":"Maximum returned rows.","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","description":"Bounded offset. Compare dataVersion across pages.","required":false,"schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}},{"name":"dataset","in":"query","description":"Available aggregate dataset.","required":false,"schema":{"type":"string","enum":["market_hourly","market_daily","coverage"],"default":"market_hourly"}},{"name":"start","in":"query","description":"Inclusive UTC start date.","required":true,"schema":{"type":"string","format":"date"}},{"name":"end","in":"query","description":"Inclusive UTC end date; at most 30 days after start.","required":true,"schema":{"type":"string","format":"date"}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 5 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataPage"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/research":{"post":{"operationId":"submitResearch","summary":"Run the existing Pump Intelligence research engine synchronously through its bounded async-job adapter.","description":"Uses the same research orchestration, report ownership, account entitlements and engine as AskPumpGPT. Developer credits are separate from three free workspace questions. Native backtest tools require the existing Quant Research entitlement; future API plans are inactive. Do not treat generated narrative or statistical estimates as observed facts.","security":[{"developerKey":[]}],"x-required-scope":"research:read","x-credit-cost":10,"parameters":[{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":true,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"additionalProperties":false,"properties":{"question":{"type":"string","minLength":5,"maxLength":2000}}},"example":{"question":"What does the observed launch cohort data show about graduation rates?"}}}},"responses":{"200":{"description":"Successful response. Cost: 10 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResponse"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/research/{id}":{"get":{"operationId":"getResearchReport","summary":"Retrieve an owned saved research result; no inference and no credit charge.","security":[{"developerKey":[]}],"x-required-scope":"research:read","x-credit-cost":0,"parameters":[{"name":"id","in":"path","description":"Report UUID belonging to the API key account.","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Account-scoped retry identity. Identical successful requests replay for zero credits; changed parameters conflict. Running or failed identities never execute again. Optional for GET; use it when retrying GET to prevent a second debit.","required":false,"schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}}],"responses":{"200":{"description":"Successful response. Cost: 0 credits; successful replays cost zero.","headers":{"X-Credits-Consumed":{"description":"Credits reserved for this response.","schema":{"type":"integer","minimum":0}},"X-Credits-Remaining":{"description":"Credits remaining in the current UTC month.","schema":{"type":"integer","minimum":0}},"X-Credits-Limit":{"description":"Current account monthly allowance.","schema":{"type":"integer","minimum":0}},"Idempotent-Replayed":{"description":"Present with value true for successful replay.","schema":{"type":"string","const":"true"}},"X-Request-ID":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResponse"}}}},"400":{"description":"Invalid parameters or JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, revoked or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unobserved entity or unowned report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Unsupported HTTP method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body deadline exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict, running or failed identity, or expired cached response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body exceeds 8 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"414":{"description":"URL exceeds 2,048 characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Send application/json for request bodies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate, concurrency or monthly credit limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Rate-limit retry delay in seconds. Credit exhaustion requires the next UTC month or an operator allowance change.","schema":{"type":"integer"}}}},"501":{"description":"Verified source capability unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Invalid, oversized or unavailable upstream response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Configuration, licensing or service access required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Execution timeout; research may continue upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/status":{"get":{"operationId":"getApiStatus","summary":"Configuration readiness only; no upstream probe or coverage guarantee.","security":[],"responses":{"200":{"description":"Safe dependency configuration and capability state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This OpenAPI 3.1 document.","security":[],"responses":{"200":{"description":"Machine-readable API specification.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"developerKey":{"type":"http","scheme":"bearer","bearerFormat":"AskPumpGPT API key","description":"A one-time-displayed personal API key created in the authenticated Developers portal. Send only to your approved gateway HTTPS origin. Never put it in a URL or public frontend bundle. Scope requirements are listed on each operation."}},"schemas":{"Error":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}},"DataRow":{"type":"object","description":"Allowlisted warehouse aggregate fields. Values retain source units; *_q are raw quote units, potentially mixing quote assets. Never assume *_q is USD or SOL. SOL values explicitly named *_sol use SOL. Empty/unknown values are null.","additionalProperties":{"type":["string","number","boolean","null"]}},"Meta":{"type":"object","required":["dataset","dataVersion","observedAt","limitations"],"properties":{"dataset":{"type":"string"},"dataVersion":{"type":"string","description":"Source release identity; restart pagination if it changes."},"observedAt":{"type":"string","format":"date-time","description":"Gateway response observation time, not data capture time."},"limitations":{"type":"array","items":{"type":"string"}},"pagination":{"type":"object","required":["limit","offset","hasMore","nextOffset"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0},"hasMore":{"type":"boolean"},"nextOffset":{"type":["integer","null"],"minimum":0}}}}},"DataPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/DataRow"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"DataEntity":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/DataRow"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ResearchResponse":{"type":"object","required":["status","report"],"properties":{"status":{"const":"ok"},"report":{"$ref":"#/components/schemas/ResearchReport"}}},"ResearchReport":{"type":"object","required":["id","question","createdAt","source","summary","keyFindings","methodology","sql","transactions","followUps"],"properties":{"id":{"type":"string","format":"uuid"},"question":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"source":{"const":"live"},"summary":{"type":"string","description":"AI-generated interpretation; inspect evidence and uncertainty."},"keyFindings":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string"},"value":{"type":"string"},"note":{"type":"string"},"trend":{"enum":["up","down","neutral"]}}}},"methodology":{"type":"array","items":{"type":"string"}},"sql":{"type":"array","description":"Evidence of executed read-only queries, never an SQL execution interface.","items":{"type":"object","required":["title","query","rowsReturned"],"properties":{"title":{"type":"string"},"query":{"type":"string"},"rowsReturned":{"type":"integer","minimum":0}}}},"transactions":{"type":"array","maxItems":0,"description":"No independently validated transaction citations are currently provided.","items":{"type":"object"}},"followUps":{"type":"array","items":{"type":"string"}},"limitations":{"type":"array","items":{"type":"string"}},"comparison":{"type":"object","required":["title","columns","rows"],"properties":{"title":{"type":"string"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"array","items":{"type":["string","number"]}}}}},"sources":{"type":"array","items":{"type":"object","required":["id","label","kind"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"enum":["database","transaction","api"]},"observedAt":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"payload":{}}}},"claims":{"type":"array","items":{"type":"object","required":["text","kind","sourceIds"],"properties":{"text":{"type":"string"},"kind":{"enum":["verified","estimate","prediction"]},"sourceIds":{"type":"array","items":{"type":"string"}},"caveat":{"type":"string"}}}}},"additionalProperties":true},"Status":{"type":"object","required":["version","status","checks","billing","capabilities","note"],"properties":{"version":{"const":"v1"},"status":{"enum":["configured","configuration_required","unavailable"]},"billing":{"const":"disabled"},"note":{"type":"string"},"checks":{"type":"object","required":["application","research","data"],"properties":{"application":{"enum":["ready","unavailable"]},"research":{"enum":["configured","configuration_required"]},"data":{"enum":["configured","configuration_required"]}}},"capabilities":{"type":"array","items":{"type":"object","required":["endpoint","available","description"],"properties":{"endpoint":{"type":"string"},"available":{"type":"boolean","description":"Implemented contract, still subject to checks/configuration."},"description":{"type":"string"}}}}}}}}}