{"openapi":"3.1.0","info":{"title":"Lucidblock Positions API","version":"0.1.0","summary":"Read-only Solana DeFi positions with explicit coverage and sourced USD values.","description":"Admin routes owned by 07-discovery-review.md (/admin/discovery/*, /admin/adapter-approvals, POST /admin/adapter-reviews,\n/admin/adapters/{id}/quarantine, /admin/adapters/{id}/rollback) are specified there and added here by T-D tasks.\n\nFor a Solana wallet, returns the lending, liquidity, staking, vault and perpetual positions found by\nverified protocol adapters, with exact per-leg amounts, sourced USD values and explicit coverage.\n\nConventions: amounts (`amount_raw`) are non-negative base-10 integer strings; `amount` and every USD\nvalue are decimal strings; unknown values are `null`, never `\"0\"`. Times are ISO 8601 UTC with second\nprecision. Addresses are base58 and case-sensitive. Absence of a position is trustworthy only for\nprotocols whose coverage status is `complete`. Totals cover the supported universe only; they are not\ntotal wallet net worth.\n\nEvery `/v1/*` response that passed the rate limiter carries `RateLimit-Limit`, `RateLimit-Remaining`\nand `RateLimit-Reset`; a 429 adds `Retry-After`. Every response carries `X-Request-Id`.\n\nWhile `PRIVATE_API_TOKEN` is configured (private alpha), every `/v1/*` route except `/v1/health`\nrequires `Authorization: Bearer <token>`.\n\nSnapshots carry display metadata (names, symbols, first-party logo URLs under /assets/v1/, provenance)\nand a trademark notice: protocol and token names and logos belong to their owners and are shown for\nidentification only (14-metadata.md). Metadata never changes ids, amounts or totals.\n","license":{"name":"Proprietary"}},"servers":[{"url":"https://api.lucidblock.xyz","description":"Production (private alpha until the v1 release gate)"},{"url":"http://127.0.0.1:8789","description":"Local wrangler dev"}],"security":[{},{"AccessToken":[]}],"tags":[{"name":"meta"},{"name":"positions"},{"name":"catalogue"},{"name":"admin"}],"paths":{"/v1/health":{"get":{"tags":["meta"],"operationId":"getHealth","summary":"Service health","security":[{}],"responses":{"200":{"description":"Service up (status ok or degraded)","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"D1 unreachable (same body shape, status down)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/":{"get":{"tags":["meta"],"operationId":"getDocsPage","summary":"HTML API documentation page","security":[{}],"responses":{"200":{"description":"Docs page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/openapi.json":{"get":{"tags":["meta"],"operationId":"getOpenApi","summary":"This contract as JSON","security":[{}],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/assets/v1/{file}":{"get":{"tags":["meta"],"operationId":"getAsset","summary":"First-party logo file (14 §3.3). Outside /v1, no access token, own per-IP limit.","security":[{}],"parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}\\.(webp|png)$"}}],"responses":{"200":{"description":"Image bytes (immutable by content hash). Cache-Control public, max-age=86400; ETag is the sha256.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"image/webp":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag)"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"ASSET_REMOVED (taken down, 14 §6.4)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/solana/wallets/{wallet}/defi-positions":{"get":{"tags":["positions"],"operationId":"getWalletPositions","summary":"Wallet DeFi positions snapshot (200) or queued scan (202)","parameters":[{"$ref":"#/components/parameters/Wallet"},{"name":"include","in":"query","description":"Comma-separated subset of underlying, rewards, valuation, metadata, tokens. Default underlying,rewards,valuation,metadata (`tokens`, the wallet token balances of D-27, only when asked for).","schema":{"type":"string","maxLength":200,"pattern":"^(underlying|rewards|valuation|metadata|tokens)(,(underlying|rewards|valuation|metadata|tokens))*$"}},{"name":"protocols","in":"query","description":"Comma-separated adapter ids (see GET /v1/solana/protocols). Default all registered.","schema":{"type":"string","maxLength":1000}},{"name":"freshness_seconds","in":"query","description":"Maximum acceptable snapshot age in seconds. Default 120.","schema":{"type":"integer","minimum":0,"maximum":86400}},{"name":"include_rewards_in_total","in":"query","description":"Count claimable reward and fee legs in totals. Requires `rewards` in `include`.","schema":{"type":"string","enum":["true","false"],"default":"false"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"Opaque cursor from page.next_cursor.","schema":{"type":"string","maxLength":200}},{"name":"wait","in":"query","description":"Long-poll (D-29). When the request would start or join a refresh scan (202, or a stale 200 with `refreshing`), hold it open up to this many seconds for the scan; if it finishes in time the response is the normal fresh 200 for the new snapshot, else exactly the response without `wait`. Counted once against rate limits. 0 (default) returns at once.","schema":{"type":"integer","minimum":0,"maximum":10,"default":0}}],"responses":{"200":{"description":"Fresh or stale snapshot","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletPositionsResponse"}}}},"202":{"description":"No snapshot yet; a bounded scan is queued","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobAccepted"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/Internal"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana/wallets/{wallet}/defi-positions/jobs/{jobId}":{"get":{"tags":["positions"],"operationId":"getScanJob","summary":"Scan job status","parameters":[{"$ref":"#/components/parameters/Wallet"},{"name":"jobId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana/protocols":{"get":{"tags":["catalogue"],"operationId":"listProtocols","summary":"Supported protocol registry","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/ProtocolStatus"}}],"responses":{"200":{"description":"Protocols","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtocolList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana/protocols/candidates":{"get":{"tags":["catalogue"],"operationId":"listCandidates","summary":"Discovered, unverified programs (never carry balances)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"Candidates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CandidateList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana/protocols/{programId}/discovery":{"get":{"tags":["catalogue"],"operationId":"getProgramDiscovery","summary":"Discovery detail for one program","parameters":[{"name":"programId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Address"}}],"responses":{"200":{"description":"Discovery detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProgramDiscovery"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/v1/solana/coverage":{"get":{"tags":["catalogue"],"operationId":"getCoverage","summary":"Category coverage and release status","responses":{"200":{"description":"Coverage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/admin/scan":{"post":{"tags":["admin"],"operationId":"adminScan","security":[{"AdminToken":[]}],"parameters":[{"name":"wallet","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Address"}}],"responses":{"200":{"description":"Scan stored","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["snapshot_id","scan_status","errors","rpc_usage"],"properties":{"snapshot_id":{"type":"string"},"scan_status":{"type":"string","enum":["complete_for_supported_protocols","partial"]},"errors":{"type":"array","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"adapter":{"type":"string"},"message":{"type":"string"}}}},"rpc_usage":{"type":"array","items":{"type":"object","required":["method","calls","estimatedCu","errors"],"properties":{"method":{"type":"string"},"calls":{"type":"integer"},"estimatedCu":{"type":"integer"},"errors":{"type":"integer"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/admin/jobs/run":{"post":{"tags":["admin"],"operationId":"adminRunJobs","security":[{"AdminToken":[]}],"responses":{"200":{"description":"One job-runner iteration","content":{"application/json":{"schema":{"type":"object","required":["claimed","results"],"properties":{"claimed":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["job_id","status","snapshot_id","errors"],"properties":{"job_id":{"type":"string"},"status":{"type":"string"},"snapshot_id":{"type":["string","null"]},"errors":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/admin/jobs":{"get":{"tags":["admin"],"operationId":"adminListJobs","security":[{"AdminToken":[]}],"parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/JobStatus"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"schema":{"type":"object","required":["jobs"],"properties":{"jobs":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/rpc-usage":{"get":{"tags":["admin"],"operationId":"adminRpcUsage","security":[{"AdminToken":[]}],"parameters":[{"name":"hours","in":"query","schema":{"type":"integer","minimum":1,"maximum":720,"default":48}}],"responses":{"200":{"description":"Hourly usage rows","content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"type":"object","required":["hour_bucket","method","calls","estimated_cu","errors"],"properties":{"hour_bucket":{"type":"integer"},"method":{"type":"string"},"calls":{"type":"integer","description":"Billed JSON-RPC members"},"http_requests":{"type":"integer"},"estimated_cu":{"type":"integer"},"errors":{"type":"integer"},"rate_limited":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/budget":{"get":{"tags":["admin"],"operationId":"adminBudget","security":[{"AdminToken":[]}],"responses":{"200":{"description":"Month-to-date RPC budget","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["month_start","month_cu_estimated","month_cu_limit","pct","state","projected_month_cu","by_method","thresholds"],"properties":{"month_start":{"$ref":"#/components/schemas/Timestamp"},"month_cu_estimated":{"type":"integer"},"month_cu_limit":{"type":"integer"},"pct":{"type":"number"},"state":{"$ref":"#/components/schemas/BudgetState"},"projected_month_cu":{"type":"integer"},"by_method":{"type":"array","items":{"type":"object","required":["method","calls","estimated_cu"],"properties":{"method":{"type":"string"},"calls":{"type":"integer"},"estimated_cu":{"type":"integer"}}}},"thresholds":{"type":"object","required":["discovery_pause_pct","scan_stop_pct"],"properties":{"discovery_pause_pct":{"type":"integer"},"scan_stop_pct":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/adapters":{"get":{"tags":["admin"],"operationId":"adminListAdapters","security":[{"AdminToken":[]}],"responses":{"200":{"description":"Compiled adapters and their runtime state","content":{"application/json":{"schema":{"type":"object","required":["adapters"],"properties":{"adapters":{"type":"array","items":{"$ref":"#/components/schemas/AdminAdapter"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/adapters/{id}/status":{"post":{"tags":["admin"],"operationId":"adminSetAdapterStatus","security":[{"AdminToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/AdapterId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","reason"],"properties":{"status":{"type":"string","enum":["disabled","enabled"]},"reason":{"type":"string","minLength":1,"maxLength":500}}}}}},"responses":{"200":{"description":"Updated adapter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminAdapter"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/admin/adapter-reviews":{"get":{"tags":["admin"],"operationId":"adminListReviews","security":[{"AdminToken":[]}],"parameters":[{"name":"adapter_id","in":"query","schema":{"$ref":"#/components/schemas/AdapterId"}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","testing","awaiting_review","approved","rejected","quarantined","published"]}}],"responses":{"200":{"description":"Reviews","content":{"application/json":{"schema":{"type":"object","required":["reviews"],"properties":{"reviews":{"type":"array","items":{"$ref":"#/components/schemas/AdapterReview"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/prices/refresh":{"post":{"tags":["admin"],"operationId":"adminRefreshPrices","security":[{"AdminToken":[]}],"responses":{"200":{"description":"One price sampler run (body defined by 05-valuation.md)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/prices":{"get":{"tags":["admin"],"operationId":"adminGetPrices","security":[{"AdminToken":[]}],"parameters":[{"name":"mints","in":"query","required":true,"schema":{"type":"string","maxLength":2300}}],"responses":{"200":{"description":"Current price rows per source (body defined by 05-valuation.md)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/cache/purge":{"post":{"tags":["admin"],"operationId":"adminPurgeCache","security":[{"AdminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"kind":{"type":"string","maxLength":64},"key_prefix":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Purged","content":{"application/json":{"schema":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/canary/run":{"post":{"tags":["admin"],"operationId":"adminRunCanary","security":[{"AdminToken":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"adapter_id":{"$ref":"#/components/schemas/AdapterId"},"dry_run":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Canary results","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"type":"object","required":["adapter_id","case","wallet_hash","pass","diffs"],"properties":{"adapter_id":{"$ref":"#/components/schemas/AdapterId"},"case":{"type":"string"},"wallet_hash":{"type":"string"},"pass":{"type":"boolean"},"quarantined":{"type":"boolean"},"diffs":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/metadata/work":{"get":{"tags":["admin"],"operationId":"adminMetadataWork","summary":"Verified subjects needing CLI work (14 §8.6)","security":[{"AdminToken":[]}],"parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["tokens","brands"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"Work list","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["subject_kind","subject_id","verified","onchain_uri","curated_logo_source","current_logo_set_id","uri_status","uri_fail_count"],"properties":{"subject_kind":{"type":"string","enum":["token","brand"]},"subject_id":{"type":"string"},"verified":{"type":"boolean"},"onchain_uri":{"type":["string","null"]},"curated_logo_source":{"type":["object","null"]},"current_logo_set_id":{"type":["string","null"]},"uri_status":{"type":["string","null"]},"uri_fail_count":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/assets/{file}":{"put":{"tags":["admin"],"operationId":"adminPutAsset","summary":"Upload one processed variant; the Worker verifies sha256, magic bytes and square 32/64/128 dimensions (14 §8.6)","security":[{"AdminToken":[]}],"parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}\\.(webp|png)$"}}],"requestBody":{"required":true,"description":"Raw image, at most 262144 bytes (the one exception to the 16 KiB admin body cap).","content":{"image/webp":{"schema":{"type":"string","format":"binary","maxLength":262144}},"image/png":{"schema":{"type":"string","format":"binary","maxLength":262144}}}},"responses":{"200":{"description":"Already stored ({\"created\": false})","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"}}}}}},"201":{"description":"Stored ({\"created\": true})","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/metadata/logo-sets":{"get":{"tags":["admin"],"operationId":"adminListLogoSets","security":[{"AdminToken":[]}],"parameters":[{"name":"review_status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"Logo sets including admin-only source and review fields","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["admin"],"operationId":"adminRegisterLogoSet","summary":"Register a processed logo set. D-24 - auto-approved when every subject is verified and the licence is displayable, else pending.","security":[{"AdminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["logo_set_id","subject_kind","subject_ids","source_kind","source_sha256","source_format","licence","variants","fetched_at"],"properties":{"logo_set_id":{"type":"string","pattern":"^[0-9a-f]{64}$"},"subject_kind":{"type":"string","enum":["token","brand"]},"subject_ids":{"type":"array","maxItems":50,"items":{"type":"string"}},"source_kind":{"type":"string","enum":["token_2022_uri","metaplex_uri","brand_kit","protocol_github","favicon","curated_file","token_list_solana_labs","placeholder"]},"source_url":{"type":["string","null"]},"source_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"source_format":{"type":"string","enum":["png","jpeg","gif","webp","svg"]},"licence":{"type":"string","enum":["issuer_published","brand_guidelines","apache-2.0","permission","own_work","unknown"]},"licence_evidence":{"type":["string","null"]},"trademark_owner":{"type":["string","null"]},"variants":{"type":"object","additionalProperties":false,"required":["w32","w64","w128","p128"],"properties":{"w32":{"type":"string","pattern":"^[0-9a-f]{64}$"},"w64":{"type":"string","pattern":"^[0-9a-f]{64}$"},"w128":{"type":"string","pattern":"^[0-9a-f]{64}$"},"p128":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"fetched_at":{"$ref":"#/components/schemas/Timestamp"}}}}}},"responses":{"201":{"description":"Registered; body states review_status (approved with reviewed_by \"auto-verified\", or pending)","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/admin/metadata/logo-sets/{id}/review":{"post":{"tags":["admin"],"operationId":"adminReviewLogoSet","security":[{"AdminToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"]},"note":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Review recorded; display_allowed recomputed","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/admin/metadata/fetch-results":{"post":{"tags":["admin"],"operationId":"adminMetadataFetchResults","security":[{"AdminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","maxItems":200,"items":{"type":"object","required":["subject_id","outcome","at"],"properties":{"subject_id":{"type":"string"},"outcome":{"type":"string","enum":["ok","dead","transient","invalid"]},"at":{"$ref":"#/components/schemas/Timestamp"}}}}}}}}},"responses":{"200":{"description":"uri_* state updated","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/metadata/token-list":{"post":{"tags":["admin"],"operationId":"adminMetadataTokenList","summary":"Load list-verified mints (archived Solana Labs token list, D-24) into D1 verified_token_list","security":[{"AdminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["source","list_sha256","mints"],"properties":{"source":{"type":"string","enum":["token_list_solana_labs"]},"list_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"mints":{"type":"array","minItems":1,"maxItems":300,"items":{"$ref":"#/components/schemas/Address"}}}}}}},"responses":{"200":{"description":"Mints stored","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["inserted","total"],"properties":{"inserted":{"type":"integer"},"total":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/metadata/takedowns":{"post":{"tags":["admin"],"operationId":"adminMetadataTakedown","security":[{"AdminToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["subject_kind","subject_id","requester_org","reason"],"properties":{"subject_kind":{"type":"string","enum":["token","brand","logo_set"]},"subject_id":{"type":"string"},"requester_org":{"type":"string","maxLength":200},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"Takedown row; effective in API responses within 5 minutes","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/metadata/takedowns/{id}/reinstate":{"post":{"tags":["admin"],"operationId":"adminMetadataReinstate","security":[{"AdminToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Reinstated","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/admin/metadata/tokens/{mint}":{"get":{"tags":["admin"],"operationId":"adminMetadataToken","security":[{"AdminToken":[]}],"parameters":[{"name":"mint","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Address"}}],"responses":{"200":{"description":"Full token_metadata row incl. provenance, source URL, flags and takedowns","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/admin/metadata/brands/{id}":{"get":{"tags":["admin"],"operationId":"adminMetadataBrand","security":[{"AdminToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9_]{1,64}$"}}],"responses":{"200":{"description":"Full brand_metadata row","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/admin/metadata/refresh":{"post":{"tags":["admin"],"operationId":"adminMetadataRefresh","summary":"Run one metadata cron iteration now (local dev has no crons)","security":[{"AdminToken":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mints":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Address"}}}}}}},"responses":{"200":{"description":"Cron iteration result","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"AccessToken":{"type":"http","scheme":"bearer","description":"PRIVATE_API_TOKEN, required on /v1/* (except /v1/health) while configured."},"AdminToken":{"type":"http","scheme":"bearer","description":"ADMIN_TOKEN. /admin/* returns 404 when it is not configured."}},"parameters":{"Wallet":{"name":"wallet","in":"path","required":true,"description":"Base58 public key decoding to exactly 32 bytes; case-sensitive.","schema":{"$ref":"#/components/schemas/Address"}}},"headers":{"XRequestId":{"schema":{"type":"string"}},"RetryAfter":{"schema":{"type":"integer","minimum":1}},"RateLimitLimit":{"schema":{"type":"integer"}},"RateLimitRemaining":{"schema":{"type":"integer"}},"RateLimitReset":{"schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"INVALID_PARAMETER, INVALID_ADDRESS, UNSUPPORTED_PROTOCOL or CURSOR_EXPIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"UNAUTHORIZED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"NOT_FOUND or JOB_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"MethodNotAllowed":{"description":"METHOD_NOT_ALLOWED","headers":{"Allow":{"schema":{"type":"string","const":"GET, HEAD, OPTIONS"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"CONFLICT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"RATE_LIMITED","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Internal":{"description":"INTERNAL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unavailable":{"description":"DB_UNAVAILABLE, QUEUE_UNAVAILABLE, SNAPSHOT_UNAVAILABLE, SCAN_FAILED, CONFIG_INVALID or RPC_BUDGET_EXHAUSTED","headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"Logo":{"type":"object","additionalProperties":false,"required":["url","sizes","png_url","placeholder","placeholder_reason","initials","color"],"properties":{"url":{"type":"string","format":"uri","description":"128 px WebP on our own host (/assets/v1/). Never a third-party URL."},"sizes":{"type":"object","additionalProperties":false,"properties":{"32":{"type":"string","format":"uri"},"64":{"type":"string","format":"uri"},"128":{"type":"string","format":"uri"}}},"png_url":{"type":"string","format":"uri"},"placeholder":{"type":"boolean"},"placeholder_reason":{"type":["string","null"],"enum":["unverified","not_available",null]},"initials":{"type":"string","maxLength":2,"description":"1–2 uppercase letters from the symbol (or '?')"},"color":{"type":"string","pattern":"^#[0-9a-f]{6}$","description":"Background colour for a text avatar, from an 8-colour palette chosen by sha256(subject id)."}}},"MetadataProvenance":{"type":"object","additionalProperties":false,"required":["name_source","symbol_source","logo_source","logo_licence","onchain_slot","updated_at"],"properties":{"name_source":{"type":["string","null"],"enum":["curated","token_2022","metaplex","token_list_solana_labs",null]},"symbol_source":{"type":["string","null"],"enum":["curated","token_2022","metaplex","token_list_solana_labs","adapter",null]},"logo_source":{"type":"string","enum":["token_2022_uri","metaplex_uri","brand_kit","protocol_github","favicon","curated_file","token_list_solana_labs","brand","placeholder"]},"logo_licence":{"type":"string","enum":["issuer_published","brand_guidelines","apache-2.0","permission","own_work"]},"onchain_slot":{"type":["integer","null"]},"updated_at":{"$ref":"#/components/schemas/Timestamp"}}},"AssetMetadata":{"type":"object","additionalProperties":false,"required":["mint","symbol","name","verified","verification","logo_url","logo","website","token_program","flags","provenance"],"properties":{"mint":{"$ref":"#/components/schemas/Address"},"symbol":{"type":["string","null"]},"name":{"type":["string","null"]},"verified":{"type":"boolean"},"verification":{"type":["string","null"],"enum":["curated","price_seed","lst_registry","protocol_receipt","token_list_solana_labs",null]},"logo_url":{"type":["string","null"],"format":"uri","description":"Equals logo.sizes.\"64\"; null only when asset serving is disabled or no placeholder file exists yet."},"logo":{"oneOf":[{"$ref":"#/components/schemas/Logo"},{"type":"null"}]},"website":{"type":["string","null"],"format":"uri","description":"https link, verified tokens only; a link, never an image source."},"token_program":{"type":["string","null"],"enum":["spl_token","token_2022",null]},"flags":{"type":"array","items":{"type":"string"},"description":"Open enum: symbol_collision, suspicious_name, metadata_mutable, metadata_malformed, metadata_truncated, metadata_pointer_foreign, metadata_unavailable, onchain_symbol_changed, logo_pending_review"},"provenance":{"$ref":"#/components/schemas/MetadataProvenance"}}},"ProtocolMetadata":{"type":"object","additionalProperties":false,"required":["id","brand_id","display_name","logo_url","logo","website","trademark_owner","provenance"],"properties":{"id":{"$ref":"#/components/schemas/AdapterId"},"brand_id":{"type":"string"},"display_name":{"type":"string"},"logo_url":{"type":["string","null"],"format":"uri"},"logo":{"oneOf":[{"$ref":"#/components/schemas/Logo"},{"type":"null"}]},"website":{"type":["string","null"],"format":"uri"},"trademark_owner":{"type":["string","null"]},"provenance":{"$ref":"#/components/schemas/MetadataProvenance"}}},"MetadataBlock":{"type":"object","additionalProperties":false,"required":["notice","assets","protocols"],"properties":{"notice":{"type":"string"},"assets":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AssetMetadata"}},"protocols":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProtocolMetadata"}}}},"Address":{"type":"string","pattern":"^[1-9A-HJ-NP-Za-km-z]{32,44}$"},"AdapterId":{"type":"string","pattern":"^[a-z0-9_]{1,64}$"},"Timestamp":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"},"AtomicAmount":{"type":"string","pattern":"^\\d+$"},"Decimal":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"},"NullableDecimal":{"type":["string","null"],"pattern":"^-?\\d+(\\.\\d+)?$"},"ErrorCode":{"type":"string","enum":["INVALID_PARAMETER","INVALID_ADDRESS","UNSUPPORTED_PROTOCOL","CURSOR_EXPIRED","UNAUTHORIZED","NOT_FOUND","JOB_NOT_FOUND","METHOD_NOT_ALLOWED","FORBIDDEN","CONFLICT","CONFIG_INVALID","RATE_LIMITED","INTERNAL","DB_UNAVAILABLE","QUEUE_UNAVAILABLE","SNAPSHOT_UNAVAILABLE","SCAN_FAILED","RPC_BUDGET_EXHAUSTED","ASSET_REMOVED"]},"ErrorEnvelope":{"type":"object","additionalProperties":false,"required":["error","request_id"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"details":{"type":"object"}}},"request_id":{"type":"string"}}},"ReleaseStatus":{"type":"string","enum":["alpha_partial","v1"]},"BudgetState":{"type":"string","enum":["normal","discovery_paused","scans_stopped"]},"Health":{"type":"object","required":["status","service","version","environment","time","db","rpc"],"properties":{"status":{"type":"string","enum":["ok","degraded","down"]},"service":{"type":"string","const":"lucidblock"},"version":{"type":"string"},"environment":{"type":"string","enum":["local","production"]},"release_status":{"$ref":"#/components/schemas/ReleaseStatus"},"time":{"$ref":"#/components/schemas/Timestamp"},"db":{"type":"string","enum":["ok","error"]},"rpc":{"type":"object","additionalProperties":false,"required":["configured_urls","keyed_endpoint"],"properties":{"configured_urls":{"type":"integer"},"keyed_endpoint":{"type":"boolean"}}},"jobs":{"type":"object","required":["queued","running","oldest_queued_age_s","last_finished_at"],"properties":{"queued":{"type":"integer"},"running":{"type":"integer"},"oldest_queued_age_s":{"type":["integer","null"]},"last_finished_at":{"type":["string","null"]}}},"prices":{"type":"object","required":["sol_usd_status","sol_usd_age_s","sources"],"properties":{"sol_usd_status":{"type":["string","null"]},"sol_usd_age_s":{"type":["integer","null"]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/PriceSourceStatus"}}}},"budget":{"type":"object","required":["month_cu_estimated","month_cu_limit","pct","state"],"properties":{"month_cu_estimated":{"type":"integer"},"month_cu_limit":{"type":"integer"},"pct":{"type":"number"},"state":{"$ref":"#/components/schemas/BudgetState"}}},"adapters":{"type":"object","required":["published","shadow","not_approved","quarantined","disabled"],"properties":{"published":{"type":"integer"},"shadow":{"type":"integer"},"not_approved":{"type":"integer"},"quarantined":{"type":"integer"},"disabled":{"type":"integer"}}},"warnings":{"type":"array","description":"Open enum. Known values release_status_downgraded (RELEASE_STATUS=v1 configured but full_scope_release_ready is false, so release_status is alpha_partial; AM-32).","items":{"type":"string"}}}},"RequestEcho":{"type":"object","required":["include","protocols","freshness_seconds","include_rewards_in_total"],"properties":{"include":{"type":"array","items":{"type":"string","enum":["underlying","rewards","valuation","metadata","tokens"]}},"protocols":{"type":["array","null"],"items":{"$ref":"#/components/schemas/AdapterId"}},"freshness_seconds":{"type":"integer"},"include_rewards_in_total":{"type":"boolean"},"limit":{"type":"integer"}}},"JobAccepted":{"type":"object","additionalProperties":false,"required":["job_id","status","wallet","retry_after_seconds","poll_url","request"],"properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued","running"]},"wallet":{"$ref":"#/components/schemas/Address"},"retry_after_seconds":{"type":"integer","minimum":1},"poll_url":{"type":"string"},"request":{"$ref":"#/components/schemas/RequestEcho"}}},"JobStatus":{"type":"string","enum":["queued","running","succeeded","failed","partial","expired"]},"Job":{"type":"object","required":["job_id","wallet","status","attempts","requested_at","started_at","finished_at","next_retry_at","retry_reason","snapshot_id"],"properties":{"job_id":{"type":"string"},"wallet":{"$ref":"#/components/schemas/Address"},"status":{"$ref":"#/components/schemas/JobStatus"},"trigger":{"type":["string","null"],"enum":["kick","cron","admin","canary",null]},"attempts":{"type":"integer"},"requested_at":{"type":["string","null"]},"started_at":{"type":["string","null"]},"finished_at":{"type":["string","null"]},"next_retry_at":{"type":["string","null"]},"retry_reason":{"type":["string","null"]},"snapshot_id":{"type":["string","null"]},"observed_slots":{"oneOf":[{"$ref":"#/components/schemas/SlotRange"},{"type":"null"}]},"errors":{"type":"array","maxItems":20,"items":{"type":"object","required":["code","adapter"],"properties":{"code":{"type":"string"},"adapter":{"type":["string","null"]},"message":{"type":"string","description":"Admin listing only"}}}}}},"SlotRange":{"type":"object","additionalProperties":false,"required":["minimum","maximum"],"properties":{"minimum":{"type":["integer","null"]},"maximum":{"type":["integer","null"]}}},"WalletPositionsResponse":{"type":"object","additionalProperties":false,"required":["chain","network","wallet","snapshot_id","release_status","as_of","observed_slots","snapshot_consistency","refreshing","refresh_job_id","freshness","coverage","positions","page","totals","request","metadata"],"properties":{"chain":{"type":"string","const":"solana"},"network":{"type":"string","const":"mainnet-beta"},"wallet":{"$ref":"#/components/schemas/Address"},"snapshot_id":{"type":["string","null"]},"release_status":{"$ref":"#/components/schemas/ReleaseStatus"},"as_of":{"$ref":"#/components/schemas/Timestamp"},"observed_slots":{"$ref":"#/components/schemas/SlotRange"},"snapshot_consistency":{"type":"string","enum":["single_slot","multi_slot","unknown"]},"refreshing":{"type":"boolean"},"refresh_job_id":{"type":["string","null"]},"freshness":{"type":"object","additionalProperties":false,"required":["age_seconds","stale","max_age_seconds"],"properties":{"age_seconds":{"type":["integer","null"]},"stale":{"type":"boolean"},"max_age_seconds":{"type":"integer"}}},"coverage":{"$ref":"#/components/schemas/Coverage"},"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"page":{"$ref":"#/components/schemas/Page"},"totals":{"oneOf":[{"$ref":"#/components/schemas/Totals"},{"type":"null"}]},"request":{"$ref":"#/components/schemas/RequestEcho"},"metadata":{"description":"Display metadata for the mints and protocols on this page (14 §7.1); null when `metadata` is not in `include`.","oneOf":[{"$ref":"#/components/schemas/MetadataBlock"},{"type":"null"}]},"tokens":{"description":"D-27 wallet token balances (native SOL plus every non-zero SPL / Token-2022 mint) for the whole snapshot, identical on every page; null unless `tokens` is in `include` or when the snapshot predates D-27. Emitted on every 200 since D-27.","oneOf":[{"$ref":"#/components/schemas/WalletTokens"},{"type":"null"}]},"tokens_total":{"description":"D-27 separate wallet-token total. Never part of, and never includes, `totals`. Null unless both `tokens` and `valuation` are in `include` (and the snapshot has a tokens section).","oneOf":[{"$ref":"#/components/schemas/TokensTotal"},{"type":"null"}]}}},"WalletTokens":{"type":"object","additionalProperties":false,"required":["scan","holdings","note"],"properties":{"scan":{"type":"object","additionalProperties":false,"required":["spl_token","token_2022","native_sol"],"properties":{"spl_token":{"type":"string","enum":["complete","error"]},"token_2022":{"type":"string","enum":["complete","error"]},"native_sol":{"type":"string","enum":["complete","error"]}}},"holdings":{"type":"array","items":{"$ref":"#/components/schemas/WalletTokenHolding"}},"note":{"type":"string"}}},"WalletTokenHolding":{"type":"object","additionalProperties":false,"required":["mint","token_program","token_accounts","amount_raw","decimals","amount","symbol","name","logo_url","verified","spam_suspected","price_usd","value_usd","valuation_status","pricing_source","price_as_of","counted_in_position","in_total"],"properties":{"mint":{"$ref":"#/components/schemas/Address","description":"Native SOL uses 11111111111111111111111111111111 (priced as wSOL)."},"token_program":{"type":"string","enum":["native","spl_token","token_2022"]},"token_accounts":{"type":"array","items":{"$ref":"#/components/schemas/Address"},"description":"Token accounts summed into this row; empty for native SOL."},"amount_raw":{"$ref":"#/components/schemas/AtomicAmount"},"decimals":{"type":"integer","minimum":0,"maximum":255},"amount":{"$ref":"#/components/schemas/Decimal"},"symbol":{"type":["string","null"]},"name":{"type":["string","null"]},"logo_url":{"type":["string","null"],"format":"uri"},"verified":{"type":"boolean"},"spam_suspected":{"type":"boolean","description":"Unverified mint that is unpriced or carries a suspicious_name / symbol_collision metadata flag. Excluded from tokens_total."},"price_usd":{"$ref":"#/components/schemas/NullableDecimal"},"value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"valuation_status":{"$ref":"#/components/schemas/LegValuationStatus"},"pricing_source":{"type":["string","null"]},"price_as_of":{"type":["string","null"],"format":"date-time"},"counted_in_position":{"type":["string","null"],"description":"Id of the DeFi position that already accounts for this token (LP mint, LST / vault share, position NFT); such rows are never in tokens_total."},"in_total":{"type":"boolean"}}},"TokensTotal":{"type":"object","additionalProperties":false,"required":["total_value_usd","known_value_usd","total_null_reasons","valuation_status","priced_count","indicative_count","stale_count","unpriced_count","counted_in_position_count","spam_suspected_count","note"],"properties":{"total_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"known_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"total_null_reasons":{"type":"array","items":{"type":"string","enum":["coverage_incomplete","unpriced_tokens","indicative_tokens","stale_tokens"]}},"valuation_status":{"type":"string","enum":["complete","partial","unavailable"]},"priced_count":{"type":"integer"},"indicative_count":{"type":"integer"},"stale_count":{"type":"integer"},"unpriced_count":{"type":"integer"},"counted_in_position_count":{"type":"integer"},"spam_suspected_count":{"type":"integer"},"note":{"type":"string"}}},"Page":{"type":"object","additionalProperties":false,"required":["limit","returned","total_positions","next_cursor","page_complete"],"properties":{"limit":{"type":"integer"},"returned":{"type":"integer"},"total_positions":{"type":"integer"},"next_cursor":{"type":["string","null"]},"page_complete":{"type":"boolean"}}},"OwnerRole":{"type":"string","enum":["authority","beneficiary","token_holder","delegate","stake_authority","withdraw_authority","unknown"]},"PositionType":{"type":"string","enum":["lending_supply","lending_borrow","liquidity_concentrated","liquidity_bins","liquidity_fungible","vault","native_staking","liquid_staking","perpetual","yield_reward","governance_staking","unclassified"]},"PositionCategory":{"type":"string","enum":["lending","concentrated_lp","bin_lp","fungible_lp","vault","native_staking","liquid_staking","perpetual","rewards"]},"LegValuationStatus":{"type":"string","enum":["priced","indicative","stale","unsupported","no_liquidity","unlicensed","error","not_requested"]},"ExclusionReason":{"type":"string","enum":["indicative","stale","unpriced","estimated","staker_only","rewards_not_included","informational","nested"]},"LegRole":{"type":"string","enum":["supplied","collateral","borrowed","liquidity","staked","share","underlying","margin","unrealized_pnl","funding","fee","reward"]},"LegContext":{"type":"object","additionalProperties":false,"required":["account","as_of_slot","status","reward_index"],"properties":{"account":{"type":["string","null"]},"as_of_slot":{"type":["integer","null"]},"status":{"type":["string","null"],"enum":["active","activating","deactivating","inactive","warming_up","unstaking",null]},"reward_index":{"type":["integer","null"],"minimum":0,"maximum":9}}},"Leg":{"type":"object","additionalProperties":false,"required":["role","mint","symbol","amount_raw","decimals","amount","price_usd","value_usd","pricing_source","price_as_of","valuation_status","confidence","claimable","amount_basis","informational","in_totals","exclusion_reason","context","market_price_usd","protocol_mark_price_usd","price_warnings"],"properties":{"role":{"$ref":"#/components/schemas/LegRole"},"mint":{"$ref":"#/components/schemas/Address"},"symbol":{"type":["string","null"]},"amount_raw":{"$ref":"#/components/schemas/AtomicAmount"},"decimals":{"type":"integer","minimum":0,"maximum":255},"amount":{"$ref":"#/components/schemas/Decimal"},"price_usd":{"$ref":"#/components/schemas/NullableDecimal"},"value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"pricing_source":{"type":["string","null"]},"price_as_of":{"type":["string","null"]},"valuation_status":{"$ref":"#/components/schemas/LegValuationStatus"},"confidence":{"type":["string","null"],"enum":["qualified","indicative",null]},"claimable":{"type":["boolean","null"]},"amount_basis":{"type":"string","enum":["exact","estimated"]},"informational":{"type":"boolean"},"in_totals":{"type":"boolean"},"exclusion_reason":{"oneOf":[{"$ref":"#/components/schemas/ExclusionReason"},{"type":"null"}]},"context":{"oneOf":[{"$ref":"#/components/schemas/LegContext"},{"type":"null"}]},"market_price_usd":{"$ref":"#/components/schemas/NullableDecimal"},"protocol_mark_price_usd":{"$ref":"#/components/schemas/NullableDecimal"},"price_warnings":{"type":"array","items":{"type":"string"}}}},"Position":{"type":"object","additionalProperties":false,"required":["id","protocol","position_type","category","position_account","owner_role","market","assets","debts","rewards","net_value_usd","known_value_usd","valuation","accounting","flags","evidence","details","warnings"],"properties":{"id":{"type":"string","pattern":"^solana:[a-z0-9_]{1,64}:[1-9A-HJ-NP-Za-km-z]{32,44}(:[A-Za-z0-9_]{1,64}){0,2}$"},"protocol":{"type":"object","additionalProperties":false,"required":["id","name","program_id","logo_url"],"properties":{"id":{"$ref":"#/components/schemas/AdapterId"},"name":{"type":"string"},"program_id":{"$ref":"#/components/schemas/Address"},"logo_url":{"type":["string","null"],"format":"uri","description":"64 px WebP on our own host; null without `metadata` in `include` or when asset serving is disabled."}}},"position_type":{"$ref":"#/components/schemas/PositionType"},"category":{"oneOf":[{"$ref":"#/components/schemas/PositionCategory"},{"type":"null"}]},"position_account":{"type":["string","null"]},"owner_role":{"$ref":"#/components/schemas/OwnerRole"},"market":{"type":["string","null"]},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Leg"}},"debts":{"type":"array","items":{"$ref":"#/components/schemas/Leg"}},"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Leg"}},"net_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"known_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"valuation":{"type":"object","additionalProperties":false,"required":["status","priced_leg_count","indicative_leg_count","unpriced_leg_count"],"properties":{"status":{"type":"string","enum":["complete","partial","unavailable","not_requested"]},"priced_leg_count":{"type":"integer"},"indicative_leg_count":{"type":"integer"},"unpriced_leg_count":{"type":"integer"}}},"accounting":{"type":"object","additionalProperties":false,"required":["counts_toward_totals","parent_position_id","carried_forward_from_snapshot"],"properties":{"counts_toward_totals":{"type":"boolean"},"parent_position_id":{"type":["string","null"]},"carried_forward_from_snapshot":{"type":["string","null"]}}},"flags":{"type":"array","description":"Open enum. Known values excluded_from_totals, staker_only, unsupported_position_kind, interest_stale, oracle_stale, incomplete_position, carried_forward, has_estimated_legs, has_indicative_legs, has_stale_legs, locked, out_of_range.","items":{"type":"string"}},"evidence":{"type":"object","additionalProperties":false,"required":["slot","adapter_version","method"],"properties":{"slot":{"type":["integer","null"]},"adapter_version":{"type":"string"},"method":{"type":"string","enum":["wallet_token","pda","program_accounts","wallet_transaction"]},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"decoder_hash":{"type":["string","null"]}}},"details":{"type":"object","description":"Adapter-specific, non-additive data (keys documented per adapter in 02/03). Amounts, prices and rates are strings.","additionalProperties":true},"warnings":{"type":"array","description":"Open enum; format code or code:detail.","items":{"type":"string"}}}},"ProtocolCoverage":{"type":"object","additionalProperties":false,"required":["id","status","adapter_version","warnings","error_code"],"properties":{"id":{"$ref":"#/components/schemas/AdapterId"},"status":{"type":"string","enum":["complete","partial","error","not_applicable","skipped"]},"adapter_version":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}},"error_code":{"type":["string","null"],"description":"Open enum. DISCOVERY_FAILED, INVALID_ADAPTER_OUTPUT, ADAPTER_EXCEPTION, BUDGET_EXCEEDED, DEADLINE_EXCEEDED, RPC_UNSUPPORTED, RPC_RATE_LIMITED, ADAPTER_QUARANTINED, ADAPTER_DISABLED, ADAPTER_NOT_APPROVED, ADAPTER_SHADOW."}}},"Coverage":{"type":"object","additionalProperties":false,"required":["status","universe","supported_protocol_count","completed_protocol_count","failed_protocol_count","skipped_protocol_count","unsupported_programs_detected","protocols","warnings"],"properties":{"status":{"type":"string","enum":["complete_for_supported_protocols","partial","stale","pending"]},"last_scan_status":{"type":"string","enum":["complete_for_supported_protocols","partial"]},"universe":{"type":"string","const":"supported_adapters_only"},"supported_protocol_count":{"type":"integer"},"completed_protocol_count":{"type":"integer"},"failed_protocol_count":{"type":"integer"},"skipped_protocol_count":{"type":"integer"},"unsupported_programs_detected":{"type":["integer","null"]},"protocols":{"type":"array","items":{"$ref":"#/components/schemas/ProtocolCoverage"}},"wallet_token_scan":{"type":"object","additionalProperties":false,"required":["spl_token","token_2022","token_accounts_found"],"properties":{"spl_token":{"type":"string","enum":["complete","error"]},"token_2022":{"type":"string","enum":["complete","error"]},"token_accounts_found":{"type":["integer","null"]}}},"warnings":{"type":"array","items":{"type":"string"}}}},"PriceSourceStatus":{"type":"object","required":["id","status","as_of"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["ok","degraded","unavailable"]},"as_of":{"type":["string","null"]}}},"Totals":{"type":"object","additionalProperties":false,"required":["total_value_usd","known_value_usd","total_null_reasons","unpriced_position_count","priced_leg_count","indicative_leg_count","unpriced_leg_count","excluded","valuation_status","include_rewards_in_total","price_sources","note"],"properties":{"total_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"known_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"total_null_reasons":{"type":"array","items":{"type":"string","enum":["coverage_incomplete","empty_universe","unpriced_legs","indicative_legs","stale_legs","peg_unverified","price_source_unavailable"]}},"unpriced_position_count":{"type":"integer"},"priced_leg_count":{"type":"integer"},"indicative_leg_count":{"type":"integer"},"unpriced_leg_count":{"type":"integer"},"excluded":{"type":"object","additionalProperties":false,"required":["indicative_value_usd","stale_value_usd","estimated_rewards_value_usd","claimable_rewards_not_included_usd","staker_only_value_usd"],"properties":{"indicative_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"stale_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"estimated_rewards_value_usd":{"$ref":"#/components/schemas/NullableDecimal"},"claimable_rewards_not_included_usd":{"$ref":"#/components/schemas/NullableDecimal"},"staker_only_value_usd":{"$ref":"#/components/schemas/NullableDecimal"}}},"valuation_status":{"type":"string","enum":["complete","partial","unavailable"]},"include_rewards_in_total":{"type":"boolean"},"price_sources":{"type":"array","items":{"$ref":"#/components/schemas/PriceSourceStatus"}},"warnings":{"type":"array","description":"Open enum of wallet-level valuation warnings (always sent by current servers; absent in older captures). `unpriced_collateral_debt_only` = some position's known value is negative because a debt is priced while its collateral is not (05 §6.2); the known value is not that position's worth.","items":{"type":"string"}},"note":{"type":"string"}}},"ProtocolStatus":{"type":"string","enum":["verified","awaiting_review","candidate","quarantined","disabled"]},"ProtocolEntry":{"type":"object","required":["id","name","status","adapter_version"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/ProtocolStatus"},"adapter_version":{"type":["string","null"]},"program_ids":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/PositionCategory"}},"capabilities":{"type":"array","items":{"type":"string"}},"artifact_hash":{"type":["string","null"]},"status_reason":{"type":["string","null"]},"category":{"type":["string","null"]},"logo_url":{"type":["string","null"],"format":"uri"},"metadata":{"oneOf":[{"$ref":"#/components/schemas/ProtocolMetadata"},{"type":"null"}]}}},"ProtocolList":{"type":"object","additionalProperties":false,"required":["universe","count","protocols"],"properties":{"universe":{"type":"string","const":"supported_adapters_only"},"count":{"type":"integer"},"protocols":{"type":"array","items":{"$ref":"#/components/schemas/ProtocolEntry"}}}},"Candidate":{"type":"object","additionalProperties":false,"required":["program_id","protocol_id","first_observed_slot","last_observed_slot","deploy_slot","upgrade_slot","source","idl_present","idl_hash","idl_source","integration_status","warnings"],"properties":{"program_id":{"$ref":"#/components/schemas/Address"},"protocol_id":{"type":["string","null"]},"first_observed_slot":{"type":["integer","null"]},"last_observed_slot":{"type":["integer","null"]},"deploy_slot":{"type":["integer","null"]},"upgrade_slot":{"type":["integer","null"]},"source":{"type":"string"},"idl_present":{"type":"boolean"},"idl_hash":{"type":["string","null"]},"idl_source":{"type":["string","null"]},"integration_status":{"type":"string"},"warnings":{"type":"array","items":{"type":"string"}}}},"CandidateList":{"type":"object","additionalProperties":false,"required":["note","candidates","limit","offset","total"],"properties":{"note":{"type":"string"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}},"ProgramDiscovery":{"type":"object","additionalProperties":false,"required":["program_id","protocol_id","integration_status","first_observed_slot","last_observed_slot","sources","upgrade_history","idl","account_structures","candidate_types","observation_count","warnings","note"],"properties":{"program_id":{"$ref":"#/components/schemas/Address"},"protocol_id":{"type":["string","null"]},"integration_status":{"type":"string"},"first_observed_slot":{"type":["integer","null"]},"last_observed_slot":{"type":["integer","null"]},"sources":{"type":"array","items":{"type":"string"}},"upgrade_history":{"type":"array","items":{"type":"object","required":["slot","bytecode_hash"],"properties":{"slot":{"type":"integer"},"bytecode_hash":{"type":["string","null"]}}}},"idl":{"type":"object","required":["present","source","hash","version","name"],"properties":{"present":{"type":"boolean"},"source":{"type":["string","null"]},"hash":{"type":["string","null"]},"version":{"type":["string","null"]},"name":{"type":["string","null"]}}},"account_structures":{"type":"array","items":{"type":"object","required":["name","discriminator_hex","size","owner_field_offset"],"properties":{"name":{"type":"string"},"discriminator_hex":{"type":["string","null"]},"size":{"type":["integer","null"]},"owner_field_offset":{"type":["integer","null"]}}}},"candidate_types":{"type":"array","items":{"type":"string"}},"observation_count":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}}},"CoverageReport":{"type":"object","required":["universe","release_status","full_scope_release_ready","adapters","categories","discovery","price_sources","note"],"properties":{"universe":{"type":"string","const":"supported_adapters_only"},"release_status":{"$ref":"#/components/schemas/ReleaseStatus"},"full_scope_release_ready":{"type":"boolean"},"adapters":{"type":"array","items":{"$ref":"#/components/schemas/ProtocolEntry"}},"categories":{"type":"array","items":{"type":"object","required":["category","status","verified_adapters"],"properties":{"category":{"$ref":"#/components/schemas/PositionCategory"},"status":{"type":"string","enum":["covered","not_covered"]},"verified_adapters":{"type":"array","items":{"$ref":"#/components/schemas/AdapterId"}}}}},"discovery":{"type":"object","required":["wallet_transaction_scan","deployment_monitoring"],"properties":{"wallet_transaction_scan":{"type":"string","enum":["not_enabled","enabled","paused_budget"]},"deployment_monitoring":{"type":"string","enum":["not_enabled","enabled","paused_budget"]}}},"price_sources":{"description":"Price source registry and licence metadata (05 §3.1, T-V13); empty until the first price refresh.","type":"array","items":{"type":"object","required":["source_id","source_type","terms_url","display_allowed","checked_at"],"properties":{"source_id":{"type":"string"},"source_type":{"type":"string"},"terms_url":{"type":["string","null"]},"display_allowed":{"type":"boolean","description":"false: informational field only (never price_usd)"},"checked_at":{"type":"string","format":"date-time"}}}},"note":{"type":"string"}}},"AdminAdapter":{"type":"object","required":["id","version","artifact_hash","runtime_status","status_reason","status_changed_by","status_changed_at","approved_review_id"],"properties":{"id":{"$ref":"#/components/schemas/AdapterId"},"version":{"type":"string"},"artifact_hash":{"type":"string"},"runtime_status":{"type":"string","enum":["published","shadow","not_approved","quarantined","disabled"]},"status_reason":{"type":["string","null"]},"status_changed_by":{"type":["string","null"]},"status_changed_at":{"type":["string","null"]},"approved_review_id":{"type":["string","null"]}}},"AdapterReview":{"type":"object","required":["review_id","adapter_id","adapter_version","artifact_hash","status","reviewer_id","reviewed_at","created_at"],"properties":{"review_id":{"type":"string"},"adapter_id":{"type":["string","null"]},"program_id":{"type":["string","null"]},"adapter_version":{"type":"string"},"artifact_hash":{"type":"string"},"idl_hash":{"type":["string","null"]},"status":{"type":"string","enum":["draft","testing","awaiting_review","approved","rejected","quarantined","published"]},"reviewer_id":{"type":["string","null"]},"reviewed_at":{"type":["string","null"]},"reviewed_notes":{"type":["string","null"]},"published_at":{"type":["string","null"]},"created_at":{"type":"string"}}}}}}