{"openapi":"3.1.0","info":{"title":"Shoal API","description":"Semantic data layer for crypto entities, events, relationships, and timelines.","version":"1.0.0","x-guidance":"Shoal API is the semantic data layer for crypto intelligence. Start with /v1/latest?window=24h for the major events happening now, or /v1/latest?window=7d and /v1/latest?window=30d for larger time horizons. Then use /v1/entities/byName?name=<query> to resolve a human name into a stable Shoal entity id, followed by /v1/entities/byId, /v1/entities/:id/relationships, and /v1/timeline/byOrganizationId?id=<entity_id>&since=<iso_timestamp> to traverse that entity. Use /v1/search?query=<text> for broader cross-entity discovery. The older /v1/organizations/* routes remain available as compatibility surfaces. Bulk feed and export surfaces are plan-gated and intentionally bounded."},"servers":[{"url":"https://api.shoal.xyz"}],"paths":{"/v1/latest":{"get":{"operationId":"getLatestEvents","summary":"Latest major events across the Shoal signal and radar surfaces","tags":["Latest"],"x-payment-info":{"pricingMode":"range","minPrice":"0.005000","maxPrice":"0.125000","protocols":["x402","mpp"]},"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"default":"24h","description":"Preset time window. Ignored if since is provided."},"description":"Preset time window. Ignored if since is provided."},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"Optional explicit ISO 8601 start timestamp within the last 30 days"},"description":"Optional explicit ISO 8601 start timestamp within the last 30 days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Number of results (max 25)"},"description":"Number of results (max 25)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":250,"default":0,"description":"Offset into the sorted result set"},"description":"Offset into the sorted result set"},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"Optional event category filter"},"description":"Optional event category filter"},{"name":"entityId","in":"query","required":false,"schema":{"type":"integer","description":"Optional canonical entity id filter"},"description":"Optional canonical entity id filter"},{"name":"topic","in":"query","required":false,"schema":{"type":"string","description":"Optional topic/natural language filter"},"description":"Optional topic/natural language filter"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["significance","recency"],"default":"significance","description":"Sort the feed by significance or recency"},"description":"Sort the feed by significance or recency"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["largest","new"],"default":"largest","description":"Convenience alias for significance vs recency sorting"},"description":"Convenience alias for significance vs recency sorting"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string"},"sort":{"type":"string"},"mode":{"type":"string"},"limit":{"type":"integer"},"offset":{"type":"integer"},"since":{"type":"string","format":"date-time"},"data":{"type":"array","items":{"type":"object"}}},"required":["window","sort","mode","limit","offset","since","data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/signal/latest":{"get":{"operationId":"getLatestSignalEvents","summary":"Latest major signal events across Shoal","tags":["Signal"],"x-payment-info":{"pricingMode":"range","minPrice":"0.005000","maxPrice":"0.125000","protocols":["x402","mpp"]},"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"default":"24h","description":"Preset time window. Ignored if since is provided."},"description":"Preset time window. Ignored if since is provided."},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"Optional explicit ISO 8601 start timestamp within the last 30 days"},"description":"Optional explicit ISO 8601 start timestamp within the last 30 days"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Number of results (max 25)"},"description":"Number of results (max 25)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":250,"default":0,"description":"Offset into the sorted result set"},"description":"Offset into the sorted result set"},{"name":"category","in":"query","required":false,"schema":{"type":"string","description":"Optional event category filter"},"description":"Optional event category filter"},{"name":"entityId","in":"query","required":false,"schema":{"type":"integer","description":"Optional canonical entity id filter"},"description":"Optional canonical entity id filter"},{"name":"topic","in":"query","required":false,"schema":{"type":"string","description":"Optional topic/natural language filter"},"description":"Optional topic/natural language filter"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["significance","recency"],"default":"significance","description":"Sort the feed by significance or recency"},"description":"Sort the feed by significance or recency"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["largest","new"],"default":"largest","description":"Convenience alias for significance vs recency sorting"},"description":"Convenience alias for significance vs recency sorting"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"window":{"type":"string"},"sort":{"type":"string"},"mode":{"type":"string"},"surface":{"type":"string"},"limit":{"type":"integer"},"offset":{"type":"integer"},"since":{"type":"string","format":"date-time"},"data":{"type":"array","items":{"type":"object"}}},"required":["window","sort","mode","surface","limit","offset","since","data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/search":{"get":{"operationId":"searchEvents","summary":"Semantic search across all intelligence events (signal + radar)","tags":["Search"],"x-payment-info":{"pricingMode":"fixed","price":"0.050000","protocols":["x402","mpp"]},"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Natural language search query (e.g. \"Arbitrum governance updates\")"},"description":"Natural language search query (e.g. \"Arbitrum governance updates\")"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"Number of results"},"description":"Number of results"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"Defaults to last 30 days if omitted"},"description":"Defaults to last 30 days if omitted"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer"},"data":{"type":"array","items":{"type":"object"}}},"required":["query","limit","data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/entities/byTopName":{"get":{"operationId":"getTopEntityByName","summary":"Resolve and return the top canonical entity match by name or alias","tags":["Entities"],"x-payment-info":{"pricingMode":"fixed","price":"0.005000","protocols":["x402","mpp"]},"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Entity name or alias to resolve"},"description":"Entity name or alias to resolve"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"Number of candidate matches to include alongside the top match"},"description":"Number of candidate matches to include alongside the top match"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"matches":{"type":"array","items":{"type":"object"}}},"required":["data","matches"]}}}},"402":{"description":"Payment Required"}}}},"/v1/signal/top":{"get":{"operationId":"getTopSignals","summary":"Top signal events ranked by score","tags":["Signal"],"x-payment-info":{"pricingMode":"range","minPrice":"0.005000","maxPrice":"0.125000","protocols":["x402","mpp"]},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Number of results (max 25)"},"description":"Number of results (max 25)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"Defaults to last 24 hours if omitted"},"description":"Defaults to last 24 hours if omitted"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer"},"data":{"type":"array","items":{"type":"object"}}},"required":["limit","data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/signal/byOrganizationId":{"get":{"operationId":"getSignalsByOrg","summary":"Signal events for a specific organization","tags":["Signal"],"x-payment-info":{"pricingMode":"range","minPrice":"0.005000","maxPrice":"0.125000","protocols":["x402","mpp"]},"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Organization ID"},"description":"Organization ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Number of results (max 25)"},"description":"Number of results (max 25)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}},"required":["data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/signal/byCategory":{"get":{"operationId":"getSignalsByCategory","summary":"Signal events filtered by category","tags":["Signal"],"x-payment-info":{"pricingMode":"range","minPrice":"0.005000","maxPrice":"0.050000","protocols":["x402","mpp"]},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","description":"Event category (e.g. partnership, funding, listing)"},"description":"Event category (e.g. partnership, funding, listing)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"Number of results (max 10)"},"description":"Number of results (max 10)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}},"required":["data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/radar/byOrganizationId":{"get":{"operationId":"getRadarByOrg","summary":"Radar events for a specific organization","tags":["Radar"],"x-payment-info":{"pricingMode":"range","minPrice":"0.002000","maxPrice":"0.050000","protocols":["x402","mpp"]},"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Organization ID"},"description":"Organization ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Number of results (max 25)"},"description":"Number of results (max 25)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}},"required":["data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/radar/byCategory":{"get":{"operationId":"getRadarByCategory","summary":"Radar events filtered by category","tags":["Radar"],"x-payment-info":{"pricingMode":"range","minPrice":"0.002000","maxPrice":"0.020000","protocols":["x402","mpp"]},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","description":"Event category"},"description":"Event category"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5,"description":"Number of results (max 10)"},"description":"Number of results (max 10)"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}},"required":["data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/organizations/byOrganizationId":{"get":{"operationId":"getOrganizationById","summary":"Get organization details by ID","tags":["Organizations"],"x-payment-info":{"pricingMode":"fixed","price":"0.005000","protocols":["x402","mpp"]},"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","description":"Organization ID"},"description":"Organization ID"},{"name":"include","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated: radar, signal"},"description":"Comma-separated: radar, signal"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","nullable":true}},"required":["data"]}}}},"402":{"description":"Payment Required"}}}},"/v1/organizations/byOrganizationName":{"get":{"operationId":"searchOrganizationsByName","summary":"Search organizations by name","tags":["Organizations"],"x-payment-info":{"pricingMode":"fixed","price":"0.005000","protocols":["x402","mpp"]},"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Organization name to search for"},"description":"Organization name to search for"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}},"required":["data"]}}}},"402":{"description":"Payment Required"}}}}},"x-discovery":{"ownershipProofs":["0xff5ecbfb456d238c023917818f8db7b711bb0f2e7a13300a4e21fa9a5831bb9a5af6d7f4a5a606bd4d396f40cdaad4c7ef15dad518b0677fc7e85b5cff2bf5251c"]}}