{"openapi":"3.1.0","info":{"title":"Bubbles Data API","version":"0.1.0","description":"Solana holder clusters from Bubbles' own on-chain pipeline. Paths and JSON shapes are compatible with the Bubblemaps v0 API shape (0.3.2), so existing clients can switch base URL. Shares are fractions 0-1. `bubblemaps_score` is kept as a field name for compatibility and holds the Bubbles score (0-100, higher = more decentralized)."},"servers":[{"url":"https://bubblemaps.dev"}],"paths":{"/v0/chains":{"get":{"summary":"Supported chains","responses":{"200":{"description":"ChainDetailsV0[]"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/search":{"get":{"summary":"Search tokens","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":2}}],"responses":{"200":{"description":"TokenDetailsV0[]"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/metadata/{chain}/{token_address}":{"get":{"summary":"Token metadata","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["solana"]}},{"name":"token_address","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"return_token_stats","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"TokenDetailsWithStatsV0"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/metadata":{"post":{"summary":"Batch token metadata (max 1000)","parameters":[{"name":"return_token_stats","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/TokenKey"}}}}},"responses":{"200":{"description":"TokenDetailsWithStatsV0[]"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/holders/{chain}/{token_address}":{"get":{"summary":"Top holders","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["solana"]}},{"name":"token_address","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":80,"enum":[80,250,500]}},{"name":"timestamp","in":"query","required":false,"schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"return_metadata","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"TokenHolderV0[]"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/map/{chain}/{token_address}":{"get":{"summary":"Bubble map: clusters, nodes (magic + time), relationships","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["solana"]}},{"name":"token_address","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":80,"enum":[80,250,500]}},{"name":"timestamp","in":"query","required":false,"schema":{"type":"string"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"use_magic_nodes","in":"query","required":false,"schema":{"type":"boolean","default":true}},{"name":"use_time_nodes","in":"query","required":false,"schema":{"type":"boolean","default":true}},{"name":"return_nodes","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"return_relationships","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"return_clusters","in":"query","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"MapDataV0 (X-Dt-Update header)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/metrics/{chain}/{token_address}":{"get":{"summary":"supply_stats + scores (Bubbles score, gini, hhi, nakamoto)","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["solana"]}},{"name":"token_address","in":"path","required":true,"schema":{"type":"string"},"description":""},{"name":"timestamp","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"MapMetricsV0"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/tokens/screenshot/{chain}/{token_address}":{"get":{"summary":"Share-card PNG URL","parameters":[{"name":"chain","in":"path","required":true,"schema":{"type":"string","enum":["solana"]}},{"name":"token_address","in":"path","required":true,"schema":{"type":"string"},"description":""}],"responses":{"200":{"description":"ScreenshotV0"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/addresses/metadata/{address}":{"get":{"summary":"Address labels","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":""}],"responses":{"200":{"description":"AddressMetadataV0"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/addresses/metadata":{"post":{"summary":"Batch address labels (1..2500)","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","minItems":1,"maxItems":2500,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"AddressMetadataV0[]"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v0/relationships/subgraph":{"post":{"summary":"Grouped transfers among 2..1000 addresses","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","minItems":2,"maxItems":1000,"items":{"type":"string"}},"context_token_key":{"$ref":"#/components/schemas/TokenKey"}}}}}},"responses":{"200":{"description":"GroupedTransferV0[]"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"TokenKey":{"type":"object","required":["chain","address"],"properties":{"chain":{"type":"string","enum":["solana"]},"address":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"loc":{"type":"array"},"msg":{"type":"string"},"type":{"type":"string"}}},"HTTPValidationError":{"type":"object","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"}}}}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-ApiKey"}}},"security":[{},{"APIKeyHeader":[]}]}