{"openapi":"3.1.0","info":{"title":"edge-data","description":"Read-only HTTP API for on-chain datasets backed by ClickHouse.","license":{"name":""},"version":"0.1.0"},"servers":[{"url":"https://edge.goldsky.com/data"}],"paths":{"/blocks/{chain}":{"get":{"tags":["blocks"],"summary":"Blocks","description":"Block headers for a chain — point lookup by number or hash, or filter over a number/timestamp range.","operationId":"get_blocks","parameters":[{"name":"chain","in":"path","description":"Chain slug (e.g. `ethereum`)","required":true,"schema":{"type":"string","enum":["apechain","arbitrum-sepolia","base","blast","bsc","celo","ethereum","flare","gravity","hyperevm","linea","matic","optimism","plasma","plume","reya","robinhood","sei","worldchain","xai","xlayer"]}},{"name":"number","in":"query","description":"Exact block number (point lookup). Conflicts with `hash` and ranges.","required":false,"schema":{"type":["integer","null"],"format":"int64","minimum":0}},{"name":"hash","in":"query","description":"Exact block hash (`0x` + 64 hex). Conflicts with `number` and ranges.","required":false,"schema":{"type":["string","null"]}},{"name":"number_gte","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64","minimum":0}},{"name":"number_lte","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64","minimum":0}},{"name":"timestamp_gte","in":"query","description":"Unix seconds. `timestamp_lte` + `sort=number_desc` + `limit=1` returns\nthe newest block at or before the timestamp (timestamp→block lookup).","required":false,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"timestamp_lte","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"sort","in":"query","description":"`number_desc` (default) or `number_asc`.","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlocksResponse"}}}},"400":{"description":"Unknown chain / bad hash / invalid cursor / unknown sort"},"422":{"description":"Conflicting filters"},"502":{"description":"Upstream ClickHouse error"}}}},"/blocks/{chain}/head":{"get":{"tags":["blocks"],"summary":"Chain head","description":"Latest indexed block for a chain, with how far behind wall-clock it is (`head_lag_seconds`).","operationId":"get_blocks_head","parameters":[{"name":"chain","in":"path","description":"Chain slug (e.g. `ethereum`)","required":true,"schema":{"type":"string","enum":["apechain","arbitrum-sepolia","base","blast","bsc","celo","ethereum","flare","gravity","hyperevm","linea","matic","optimism","plasma","plume","reya","robinhood","sei","worldchain","xai","xlayer"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockHeadResponse"}}}},"400":{"description":"Unknown chain"},"502":{"description":"Upstream ClickHouse error / no data for chain"}}}},"/feeds/wallets/balances":{"get":{"tags":["feeds"],"summary":"Wallet balances","description":"The latest balance of every token one wallet holds across chains, EVM natives included, with USD value and the wallet's total.","operationId":"get_feeds_balances","parameters":[{"name":"address","in":"query","description":"The one wallet this request is about. Required.","required":true,"schema":{"type":["string","null"]}},{"name":"chains","in":"query","description":"Comma-separated canonical chain slugs; default all. Supported: `arbitrum_one`, `arc`, `base`, `bsc`, `ethereum`, `optimism`, `polygon`, `robinhood`.","required":false,"schema":{"type":["string","null"]}},{"name":"token_address","in":"query","description":"Comma-separated token contracts; the zero address selects natives.","required":false,"schema":{"type":["string","null"]}},{"name":"token_symbol","in":"query","description":"Comma-separated symbols, matched case-insensitively against the\nserved `token_symbol` (token metadata first, else the registry).","required":false,"schema":{"type":["string","null"]}},{"name":"include_unknown_price","in":"query","description":"Default false: hide tokens Goldsky has no price source for (neither\ntier-0 nor a canonical registry member). Such a token may still be\nserved unpriced when included; a priceable one may lack a price.","required":false,"schema":{"type":["boolean","null"]}},{"name":"min_value_usd","in":"query","description":"Dust filter on `value_usd`: rows below it are dropped, and so are\nunpriced rows (no value clears any threshold). Applies to\n`total_value_usd` too.","required":false,"schema":{"type":["number","null"],"format":"double"}},{"name":"include_historical","in":"query","description":"Also return zero balances: fully sold tokens, and natives the wallet\nholds none of. Default false.","required":false,"schema":{"type":["boolean","null"]}},{"name":"page_size","in":"query","description":"Default 100, max 1000.","required":false,"schema":{"type":["integer","null"],"format":"int32","minimum":0}},{"name":"page_token","in":"query","description":"`pagination.next_page_token` (or `prev_page_token`) from a previous\nresponse.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedsBalancesResponse"}}}},"400":{"description":"Bad request / invalid page_token"},"502":{"description":"Upstream ClickHouse error"},"503":{"description":"Native balances unavailable on the chains named in `error.chains`; retry after `Retry-After` seconds"}}}},"/feeds/wallets/transfers":{"get":{"tags":["feeds"],"summary":"Wallet transfers","description":"Every token movement for one wallet across chains, newest first — token metadata, USD value at transfer time, and the counterparty on each row.","operationId":"get_feeds_transfers","parameters":[{"name":"address","in":"query","description":"The one wallet this request is about. Required.","required":true,"schema":{"type":["string","null"]}},{"name":"chains","in":"query","description":"Comma-separated canonical chain slugs; default all. Supported: `arbitrum_one`, `arc`, `base`, `bsc`, `ethereum`, `optimism`, `polygon`, `robinhood`.","required":false,"schema":{"type":["string","null"]}},{"name":"token_address","in":"query","description":"Comma-separated token contract addresses, up to 100. The zero\naddress selects each chain's native token.","required":false,"schema":{"type":["string","null"]}},{"name":"token_symbol","in":"query","description":"Comma-separated symbols, matched case-insensitively against the\nserved `token_symbol` (token metadata first, else the registry).","required":false,"schema":{"type":["string","null"]}},{"name":"include_unknown_price","in":"query","description":"Default false: hide tokens Goldsky has no price source for (neither\ntier-0 nor a canonical registry member). Such a token may still be\nserved unpriced when included; a priceable one may lack a price.","required":false,"schema":{"type":["boolean","null"]}},{"name":"transfer_type","in":"query","description":"Comma list of `native` and `erc20`. NFT transfer types (`erc721`,\n`erc1155`) are not supported yet and return `400`.","required":false,"schema":{"type":["string","null"]}},{"name":"direction","in":"query","description":"`in` or `out`, relative to `address`.","required":false,"schema":{"type":["string","null"]}},{"name":"from","in":"query","description":"Inclusive RFC 3339 lower bound on `block_timestamp`.","required":false,"schema":{"type":["string","null"]}},{"name":"to","in":"query","description":"Inclusive RFC 3339 upper bound on `block_timestamp`.","required":false,"schema":{"type":["string","null"]}},{"name":"from_block","in":"query","description":"Inclusive lower bound on `block_number`; needs exactly one chain.","required":false,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"to_block","in":"query","description":"Inclusive upper bound on `block_number`; needs exactly one chain.","required":false,"schema":{"type":["integer","null"],"format":"int64"}},{"name":"page_size","in":"query","description":"Default 100, max 1000.","required":false,"schema":{"type":["integer","null"],"format":"int32","minimum":0}},{"name":"page_token","in":"query","description":"`pagination.next_page_token` (or `prev_page_token`) from a previous\nresponse.","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedsTransfersResponse"}}}},"400":{"description":"Bad request / invalid page_token"},"422":{"description":"Conflicting filters"},"502":{"description":"Upstream ClickHouse error"}}}},"/polymarket/activity":{"get":{"tags":["polymarket"],"summary":"Activities","description":"Wallet activity newest first — trade fills and matches, plus splits, merges and redeems, with the counterparty on each maker row.","operationId":"get_activity","parameters":[{"name":"address","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"token_id","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"event_type","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"side","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"order_type","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"start_time","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"end_time","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"start_block","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64","minimum":0}},{"name":"end_block","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int64","minimum":0}},{"name":"min_amount_usdc","in":"query","required":false,"schema":{"type":["number","null"],"format":"double"}},{"name":"sort","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32","minimum":0},"example":3},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivityResponse"}}}},"400":{"description":"Bad request / invalid cursor / unknown sort"},"502":{"description":"Upstream ClickHouse error"}}}},"/polymarket/balances":{"get":{"tags":["polymarket"],"summary":"Balances","description":"Conditional-token balances per owner, as of the latest indexed block for each holding.","operationId":"get_balances","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"example":"0x0000000000002d4249a9b7976dc47d3cff1a54a2"},{"name":"token_id","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"contract_address","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"token_type","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"min_balance","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"as_of_block","in":"query","description":"Latest known balance at or before block X by insert order — not a strict block-X reconstruction. A true historical endpoint is planned.","required":false,"schema":{"type":["integer","null"],"format":"int64","minimum":0}},{"name":"sort","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32","minimum":0},"example":3},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalancesResponse"}}}},"400":{"description":"Bad request / invalid cursor / unknown sort"},"502":{"description":"Upstream ClickHouse error"}}}},"/polymarket/positions":{"get":{"tags":["polymarket"],"summary":"Positions","description":"Open positions per wallet and market token — size, average entry price, and running realized PnL.","operationId":"get_positions","parameters":[{"name":"address","in":"query","required":true,"schema":{"type":"string"},"example":"0x0000000000002d4249a9b7976dc47d3cff1a54a2"},{"name":"token_id","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"min_amount","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"include_zero","in":"query","required":false,"schema":{"type":["boolean","null"]}},{"name":"sort","in":"query","description":"Sort by amount_desc (default), amount_asc, realized_pnl_desc, or\nlast_updated_at_desc, with token_id ascending for ties. NULL sort values\nsort as zero: before positive amounts in amount_asc and before losses in\nrealized_pnl_desc. Returned values remain NULL.","required":false,"schema":{"type":["string","null"]}},{"name":"limit","in":"query","required":false,"schema":{"type":["integer","null"],"format":"int32","minimum":0},"example":3},{"name":"cursor","in":"query","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionsResponse"}}}},"400":{"description":"Bad request / invalid cursor / unknown sort"},"502":{"description":"Upstream ClickHouse error"}}}}},"components":{"schemas":{"ActivityItem":{"type":"object","required":["block_number","id","event_type","side","order_type"],"properties":{"address":{"type":["string","null"],"description":"Owner wallet address (40-hex, 0x-prefixed). Same field name and\nsemantics across positions, balances, and activity."},"amount_shares":{"type":["number","null"],"format":"double"},"amount_usdc":{"type":["number","null"],"format":"double"},"block_number":{"type":"integer","format":"int64"},"block_timestamp":{"type":["integer","null"],"format":"int64"},"builder":{"type":["string","null"]},"counterparty_address":{"type":["string","null"],"description":"Wallet of the other side of this trade, when known. `null` for\n`order_type=taker` rows (the counterparty is the settlement venue,\nnot a user); for `order_type=maker` rows, the matching taker's wallet.\nTo resolve the taker leg, find the sibling row(s) in the same result\npage with the same `transaction_hash` and `token_id` and opposite `side`."},"event_type":{"type":"string"},"fee":{"type":["number","null"],"format":"double","description":"Fee paid by this side of the trade, in USDC. Known data-quality issue:\nthe basis (`amount_usdc` vs `amount_shares`) is inconsistent across some\nmaker/taker pairs in the source data. Treat values with skepticism."},"id":{"type":"string"},"order_id":{"type":["string","null"]},"order_type":{"type":"string"},"price":{"type":["number","null"],"format":"double"},"side":{"type":"string"},"token_id":{"type":["string","null"]},"transaction_hash":{"type":["string","null"]}}},"ActivityResponse":{"type":"object","required":["data","limit"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ActivityItem"}},"limit":{"type":"integer","format":"int32","minimum":0},"next_cursor":{"type":["string","null"]}}},"BalanceItem":{"type":"object","required":["address","token_id","balance"],"properties":{"address":{"type":"string","description":"Owner wallet address (40-hex, 0x-prefixed). Same field name and\nsemantics across positions, balances, and activity."},"balance":{"type":"string","format":"decimal-string","example":"123456789"},"block_number":{"type":["integer","null"],"format":"int64"},"block_timestamp":{"type":["integer","null"],"format":"int64"},"contract_address":{"type":["string","null"]},"token_id":{"type":"string"},"token_type":{"type":["string","null"]}}},"BalancesResponse":{"type":"object","required":["data","limit"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BalanceItem"}},"limit":{"type":"integer","format":"int32","minimum":0},"next_cursor":{"type":["string","null"]}}},"BlockHeadResponse":{"type":"object","required":["chain","number","timestamp","head_lag_seconds"],"properties":{"chain":{"type":"string"},"head_lag_seconds":{"type":"integer","format":"int64","description":"Seconds between now and the head block — the data-freshness signal."},"number":{"type":"integer","format":"int64","description":"Canonical head block number (tombstoned orphans excluded).","minimum":0},"timestamp":{"type":"integer","format":"int64","description":"Head block time, unix seconds."}}},"BlockItem":{"type":"object","required":["chain","number","timestamp","hash","parent_hash","author","size","receipts_root","transactions_root","state_root","uncles_hash","transaction_count"],"properties":{"author":{"type":"string"},"base_fee_per_gas":{"type":["integer","null"],"format":"int64","minimum":0},"chain":{"type":"string"},"gas_limit":{"type":["integer","null"],"format":"int64","minimum":0},"gas_used":{"type":["integer","null"],"format":"int64","minimum":0},"hash":{"type":"string"},"number":{"type":"integer","format":"int64","minimum":0},"parent_hash":{"type":"string"},"receipts_root":{"type":"string"},"size":{"type":"integer","format":"int64","minimum":0},"state_root":{"type":"string"},"timestamp":{"type":"integer","format":"int64","description":"Block time, unix seconds."},"transaction_count":{"type":"integer","format":"int32","minimum":0},"transactions_root":{"type":"string"},"uncles_hash":{"type":"string"}}},"BlocksResponse":{"type":"object","required":["data","limit"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BlockItem"}},"limit":{"type":"integer","format":"int32","minimum":0},"next_cursor":{"type":["string","null"]}}},"FeedsBalanceItem":{"type":"object","required":["chain","chain_family","token_address","balance_raw","block_number","block_timestamp"],"properties":{"balance_raw":{"type":"string"},"block_number":{"type":"integer","format":"int64"},"block_timestamp":{"type":"string"},"chain":{"type":"string"},"chain_family":{"type":"string"},"last_priced_at":{"type":["string","null"],"description":"RFC 3339 as-of time of the observed price behind `price_usd`: the\nstart of Goldsky's 60 s price bucket, or CoinGecko's own last update\nwhen the price is CoinGecko's (the long-tail fallback). Never older than\nthe configured price window (default 4 h): an older price is not\nserved. **Null beside a non-null\n`price_usd` means asserted at par (a tier-0 stablecoin, or a member of\none), not stale** — a `now - last_priced_at > threshold` filter must\nexempt it or it drops every stablecoin. Null beside a null\n`price_usd`: unpriced."},"price_usd":{"type":["number","null"],"format":"double"},"token_address":{"type":"string"},"token_decimals":{"type":["integer","null"],"format":"int32"},"token_logo_url":{"type":["string","null"]},"token_name":{"type":["string","null"]},"token_symbol":{"type":["string","null"]},"value_usd":{"type":["number","null"],"format":"double"}}},"FeedsBalancesResponse":{"type":"object","required":["address","total_value_usd","data","pagination"],"properties":{"address":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedsBalanceItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"total_value_usd":{"type":"number","format":"double","description":"Sum of `value_usd` over every balance that matches the request's\nfilters, across all pages. Balances without a USD value add nothing,\nso read it as a lower bound."}}},"FeedsTransferItem":{"type":"object","required":["chain","chain_family","block_number","block_timestamp","transaction_hash","direction","token_address","amount_raw","transfer_type"],"properties":{"amount_raw":{"type":"string"},"amount_usd":{"type":["number","null"],"format":"double"},"block_number":{"type":"integer","format":"int64"},"block_timestamp":{"type":"string"},"chain":{"type":"string"},"chain_family":{"type":"string"},"direction":{"type":"string"},"from_address":{"type":["string","null"]},"from_label":{"type":["string","null"]},"price_usd":{"type":["number","null"],"format":"double"},"to_address":{"type":["string","null"]},"to_label":{"type":["string","null"]},"token_address":{"type":"string"},"token_decimals":{"type":["integer","null"],"format":"int32"},"token_logo_url":{"type":["string","null"]},"token_name":{"type":["string","null"]},"token_symbol":{"type":["string","null"]},"transaction_hash":{"type":"string"},"transfer_type":{"type":"string"}}},"FeedsTransfersResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedsTransferItem"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Pagination":{"type":"object","required":["page_size"],"properties":{"next_page_token":{"type":["string","null"],"description":"Pass back as `page_token` for the next page; `null` on the last page."},"page_size":{"type":"integer","format":"int32","minimum":0},"prev_page_token":{"type":["string","null"],"description":"Pass back as `page_token` for the previous page; `null` on the first\npage. Going back re-reads the rows, so a row that changed position\nsince (a balance whose value moved) can appear on a different page."}}},"PositionItem":{"type":"object","required":["address","token_id"],"properties":{"address":{"type":"string","description":"Owner wallet address (40-hex, 0x-prefixed). Same field name and\nsemantics across positions, balances, and activity."},"amount":{"type":["string","null"]},"avg_price":{"type":["string","null"]},"block_number":{"type":["integer","null"],"format":"int64"},"last_updated_at":{"type":["number","null"],"format":"double","description":"Pipeline upsert time (seconds, microsecond precision). Not the on-chain\nblock timestamp — two rows with different `block_number` can share this\nvalue when upserted in the same pipeline batch."},"realized_pnl":{"type":["string","null"]},"token_id":{"type":"string"},"total_bought":{"type":["string","null"]}}},"PositionsResponse":{"type":"object","required":["data","limit"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PositionItem"}},"limit":{"type":"integer","format":"int32","minimum":0},"next_cursor":{"type":["string","null"]}}}},"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"x-api-key","description":"Goldsky API key (also accepted: `?key=` or `Authorization: Bearer`)."}}},"security":[{"api_key":[]}],"tags":[{"name":"polymarket","description":"Polymarket: positions with running PnL, token balances, and trade activity"},{"name":"blocks","description":"Block headers: number↔timestamp lookups, ranges, chain head"},{"name":"feeds","description":"Wallet feeds: one address in, its transfers or its balances out"}],"x-goldsky-providers":{"blocks":{"logo_url":"https://app.goldsky.com/apple-touch-icon.png","name":"Blocks"},"feeds":{"logo_url":"https://app.goldsky.com/apple-touch-icon.png","name":"Feeds"},"polymarket":{"logo_url":"https://polymarket.com/icons/apple-touch-icon.png","name":"Polymarket"}}}