--- canonical_url: "https://docs.composio.dev/toolkits/surf" markdown_url: "https://docs.composio.dev/toolkits/surf.md" product: "platform" version: null last_updated: null --- # Surf Surf provides AI-ready financial, crypto, prediction-market, equity, on-chain, news, search, and web data through a unified API. - **Category:** artificial intelligence - **Auth:** API_KEY - **Composio-managed OAuth available?** N/A - **Tools:** 122 - **Triggers:** 0 - **Slug:** `SURF` - **Version:** 00000000_00 ## Tools ### Cancel Asynchronous Blockchain SQL Job **Slug:** `SURF_CANCEL_ONCHAIN_SQL_JOB` Durably request cancellation of an asynchronous blockchain SQL job and return its current state. Queued jobs become canceled immediately; running queries stop asynchronously, so poll the job until it is canceled or failed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `job_id` | string | Yes | Asynchronous SQL job identifier to cancel. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Submit Asynchronous Blockchain SQL Job **Slug:** `SURF_CREATE_ONCHAIN_SQL_JOB` Submit a read-only ClickHouse SQL query for durable background execution and return its stable job and query identifiers immediately. Equivalent retained queries with the same max_rows, or requests reusing an Idempotency-Key, return the existing job. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sql` | string | Yes | Exact read-only ClickHouse SQL to execute asynchronously. The submitted SQL and date range are preserved. | | `max_rows` | integer | No | Maximum number of result rows to retain. | | `idempotency_key` | string | No | Stable client-generated key. Reusing it returns the retained existing job instead of starting another query. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### DEX Token OHLCV Price **Slug:** `SURF_GET_DEX_TOKEN_PRICE` Return USD DEX-pool-weighted OHLCV bars for one token identified by chain and contract address. Use this for DEX-native or newly launched tokens; use the standard market price action for major listed assets. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of a custom range as Unix seconds or YYYY-MM-DD. Must be used with `from_`; together they override `time_range`. | | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "optimism" | "polygon" | "avalanche" | "solana") | Yes | Chain the token lives on. Can be `ethereum`, `base`, `bsc`, `arbitrum`, `optimism`, `polygon`, `avalanche`, or `solana`. | | `from_` | string | No | Start of a custom range as Unix seconds or YYYY-MM-DD. Must be used with `to`; together they override `time_range`. | | `address` | string | Yes | Token contract address: 0x-prefixed 42-character hex for EVM chains or base58 for Solana. Do not pass a ticker symbol. | | `interval` | string ("1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "12h" | "1d" | "7d") | No | Candle bucket size. Sub-day intervals from `1m` through `4h` are typically best for active DEX analysis. | | `time_range` | string ("1h" | "6h" | "12h" | "24h" | "7d" | "30d" | "90d" | "180d" | "365d" | "max") | No | Historical window. `max` returns at most 1500 bars for the selected interval. Ignored when both `from_` and `to` are set. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Balance Sheet **Slug:** `SURF_GET_EQUITY_BALANCE_SHEET` Return standardized balance-sheet periods for a US-listed equity. Each metric includes an availability status, and unavailable values are null. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of financial periods to return (1-100). | | `period` | string ("quarterly" | "annual") | No | Financial period to return. | | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Price Candles **Slug:** `SURF_GET_EQUITY_CANDLES` Return historical OHLCV candles and the latest traded price for a US-listed equity. Candles are ordered by timestamp ascending; historical data and the latest price use independent freshness windows. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive end date in YYYY-MM-DD format; defaults to the current date in US Eastern time. | | `interval` | string ("day" | "week" | "month" | "year") | No | Candle interval. | | `start_date` | string | No | Inclusive start date in YYYY-MM-DD format; defaults to one year before end_date. | | `interval_multiplier` | integer | No | Number of intervals represented by each candle. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Cash Flow **Slug:** `SURF_GET_EQUITY_CASH_FLOW` Return paginated standardized cash-flow periods for a US-listed equity. The response preserves serving-layer values, status, origin, and period metadata. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of financial periods to return (1-100). | | `period` | string ("quarterly" | "ytd" | "annual" | "ttm") | No | Financial period to return. | | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Profile **Slug:** `SURF_GET_EQUITY_COMPANY_PROFILE` Return a standardized stock company profile or ETF product profile, including its business description and source-update metadata. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `symbol` | string | Yes | US equity ticker symbol. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Financial Metrics **Slug:** `SURF_GET_EQUITY_FINANCIAL_METRICS` Return paginated standardized financial ratios, growth measures, per-share values, and valuation metrics for a US-listed equity. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of financial periods to return (1-100). | | `period` | string ("quarterly" | "annual" | "ttm") | No | Financial metric period. | | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Income Statement **Slug:** `SURF_GET_EQUITY_INCOME_STATEMENT` Return standardized income-statement periods for a US-listed equity. The API passes through available periods and does not synthesize missing periods or financial values. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of financial periods to return (1-100). | | `period` | string ("quarterly" | "ytd" | "annual" | "ttm") | No | Financial period to return. | | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Latest Equity Filings **Slug:** `SURF_GET_EQUITY_LATEST_FILINGS` Return the most recently accepted periodic SEC filings across US equities. Includes 10-K, 10-Q, 20-F, 40-F and amendments, excludes 8-K, and returns one filing per reporting series. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of filings to return (1-20). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Latest Equity Financials **Slug:** `SURF_GET_EQUITY_LATEST_FINANCIALS` Return the most recently published current-serving TTM financials across US equities, optionally filtered by a minimum current market capitalization. Results contain one company per reporting series. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of companies to return (1-20). | | `market_cap_min` | number | No | Minimum current-serving market capitalization in USD. Omit to disable this filter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Metadata **Slug:** `SURF_GET_EQUITY_META` Return lightweight identity, logo, and latest USD price metadata for one or more US-listed stocks or ETFs. Symbols are returned in request order. Company and fund identity is cached for 24 hours; prices are cached independently for 1 minute. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `symbols` | array | Yes | US stock or ETF ticker symbols to look up, with at most 20 symbols. | | `include_tokenized` | boolean | No | Include issuer-minted crypto tokens that track each equity, with their chains and contract addresses. Omit unless tokenized counterparts are needed. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Financial Overview **Slug:** `SURF_GET_EQUITY_OVERVIEW` Return a paginated financial overview for a US-listed equity. Values are served as reported or derived by the financial-data serving layer; missing values remain explicit nulls and are not recalculated by this API. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of financial periods to return (1-100). | | `period` | string ("quarterly" | "ytd" | "annual" | "ttm") | No | Financial period. | | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive latest period end date in YYYY-MM-DD format. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Order Book Depth **Slug:** `SURF_GET_EXCHANGE_DEPTH` Return bid and ask order-book levels for an exchange market, including spread, spread percentage, mid-price, and total bid and ask depth. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pair` | string | Yes | Trading pair in BASE/QUOTE form. | | `type` | string ("spot" | "swap" | "perpetual" | "perp") | No | Market type. Use `spot` for spot trading or `swap`, `perpetual`, or `perp` for perpetual contracts. | | `limit` | integer | No | Number of bid and ask price levels to return (1-100). | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "mexc" | "upbit" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid") | No | Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Funding Rate History **Slug:** `SURF_GET_EXCHANGE_FUNDING_HISTORY` Return historical funding rate records for a perpetual contract. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pair` | string | Yes | Trading pair for the perpetual contract. | | `from_` | string | No | Start of the time range as Unix seconds, YYYY-MM-DD, or ISO 8601. Some exchanges return only recent data regardless of this value. | | `limit` | integer | No | Maximum records to return (1-500). For a later window, pass the last returned timestamp as from_. | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget" | "gate" | "htx" | "mexc" | "bitfinex" | "bitmex" | "hyperliquid") | No | Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange OHLCV Candlesticks **Slug:** `SURF_GET_EXCHANGE_KLINES` Return exchange OHLCV candlesticks with high, low, and total-volume statistics for the returned period. Set `type` to a perpetual-market variant to query perpetual contracts instead of spot markets. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pair` | string | Yes | Trading pair in BASE/QUOTE form. | | `type` | string ("spot" | "swap" | "perpetual" | "perp") | No | Market type. Use `spot` for spot trading or `swap`, `perpetual`, or `perp` for perpetual contracts. | | `from_` | string | No | Start of the time range as Unix seconds, YYYY-MM-DD, or an ISO 8601 date-time. | | `limit` | integer | No | Maximum candles to return (1-1000). Exchanges may enforce a lower limit. For a later window, make another call with `from_` set to the last returned candle timestamp. | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "htx" | "kucoin" | "mexc" | "upbit" | "bitfinex" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid") | No | Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC. | | `interval` | string ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M") | No | Candle bucket duration. This endpoint does not accept `time_range`; use `from_` and `limit` to control the window. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Long/Short Ratio History **Slug:** `SURF_GET_EXCHANGE_LONG_SHORT_RATIO` Return historical long/short ratios for a perpetual contract. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pair` | string | Yes | Perpetual contract pair in BASE/QUOTE form. | | `from_` | string | No | Start of the time range as Unix seconds, YYYY-MM-DD, or ISO 8601. Binance retains up to the last 30 days; other exchanges may differ. | | `limit` | integer | No | Maximum number of ratio points to return (1-500). | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget") | No | Exchange identifier. | | `interval` | string ("1h" | "4h" | "1d") | No | Bucket size for each ratio point. This endpoint does not accept time_range; use from_ and limit to control the window. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Trading Pairs **Slug:** `SURF_GET_EXCHANGE_MARKETS` Return trading pairs available on an exchange, including base and quote currencies, market type, active status, and default fee rates. Use the returned pair values with other exchange actions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `base` | string | No | Base currency filter. | | `type` | string ("spot" | "swap" | "future" | "option" | "perpetual" | "perp") | No | Market type filter. `perpetual` and `perp` are aliases for swap markets. | | `limit` | integer | No | Maximum number of markets to return (1-5000). | | `quote` | string | No | Quote currency filter. | | `search` | string | No | Fuzzy search over the pair, base currency, and quote currency. | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "htx" | "kucoin" | "mexc" | "upbit" | "bitfinex" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid") | No | Exchange identifier. Defaults to Binance; select another venue to list only that exchange's markets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Perpetual Contract Snapshot **Slug:** `SURF_GET_EXCHANGE_PERP` Return a perpetual futures snapshot for a trading pair, including current funding, open interest, mark price, and index price data. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pair` | string | Yes | Trading pair in BASE/QUOTE form. Surf adds the perpetual settle suffix from the quote currency automatically. | | `fields` | array | No | Data groups to include: `funding` for current funding data and `oi` for open interest. Each group may be selected at most once. | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget" | "htx" | "bitfinex" | "bitmex" | "hyperliquid") | No | Exchange identifier. Hyperliquid uses USDC-settled perpetuals, such as BTC/USDC:USDC. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Ticker Price **Slug:** `SURF_GET_EXCHANGE_PRICE` Return the real-time ticker for an exchange trading pair, including the last price, best bid and ask, 24-hour high, low, volume, and price change. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pair` | string | Yes | Trading pair in BASE/QUOTE form. | | `type` | string ("spot" | "swap" | "perpetual" | "perp") | No | Market type. Use `spot` for spot trading or `swap`, `perpetual`, or `perp` for perpetual contracts. | | `exchange` | string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "htx" | "kucoin" | "mexc" | "upbit" | "bitfinex" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid") | No | Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fund Profile Detail **Slug:** `SURF_GET_FUND_DETAIL` Return a crypto VC fund's full profile, including its description, jurisdiction, unique invested-project count, links, X accounts, team members, and recent research. This does not return individual investments. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fund_id` | string | No | Surf fund UUID. Provide fund_id or fund_name. Prefer this exact identifier when available; it takes priority over fund_name. | | `fund_name` | string | No | Fuzzy fund name. Provide fund_id or fund_name, and use fund_name only when fund_id is unavailable. Ambiguous names may match an unexpected fund. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Account Portfolio **Slug:** `SURF_GET_HYPERLIQUID_ACCOUNT` Return a Hyperliquid wallet's point-in-time portfolio across perpetuals, spot, vaults, and HYPE staking. Use total_value_usd for the best-effort whole-account value and unpriced_token_count to determine whether it excludes unpriced spot holdings. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name, such as vitalik.eth. Solana addresses are not supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Market Candles **Slug:** `SURF_GET_HYPERLIQUID_CANDLES` Return Hyperliquid market OHLCV candles ordered by open time ascending for a required half-open [from_, to) window. The window may contain at most 5,000 candles, so use a larger interval or narrower dates for long histories. This market-data action does not require a wallet address. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | Yes | Window end as Unix seconds, an ISO 8601 date-time, or a UTC date. A date means the end of that day. | | `from_` | string | Yes | Window start as Unix seconds, an ISO 8601 date-time, or a UTC date. | | `symbol` | string | Yes | Hyperliquid market ID, such as BTC, kPEPE, xyz:GOLD, the canonical PURR/USDC spot pair, or an @index spot market. | | `interval` | string ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M") | No | Candle granularity. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Open & Recent Orders **Slug:** `SURF_GET_HYPERLIQUID_ORDERS` Return a wallet's live resting orders and recent terminal orders. Use the open section to inspect active stops, take-profits, and limits, and the historical section for final filled, canceled, or rejected statuses. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | Yes | Wallet address: a 0x EVM address or an ENS name. Solana addresses are not supported. | | `open_limit` | integer | No | Maximum open orders to return. `open_total` reports the count before this limit is applied. | | `historical_limit` | integer | No | Maximum terminal orders to return, newest first. `historical_total` reports the count before this limit is applied. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Trading Performance **Slug:** `SURF_GET_HYPERLIQUID_PERFORMANCE` Return a wallet's lifetime funding-excluded realized trading performance, live open positions, unrealized PnL, and perpetual clearinghouse equity. This point-in-time summary has no date window or trade list; use account portfolio data when spot and vault equity must be included. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Open Positions **Slug:** `SURF_GET_HYPERLIQUID_POSITIONS` Return a wallet's open Hyperliquid perpetual positions with leverage, unrealized PnL, ROE, funding, liquidation risk, and its cross-margin summary. When a cross position has no liquidation price, use the account-level margin_ratio as the liquidation-proximity signal. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `dex` | string ("main_dex" | "xyz" | "flx" | "vntl" | "hyna" | "km" | "abcd" | "cash" | "para" | "mkts") | No | Market scope. Omit or use `main_dex` for Hyperliquid's native market; otherwise select a builder market. | | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name, such as vitalik.eth. Solana addresses are not supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Closed Trade Funding and Leverage **Slug:** `SURF_GET_HYPERLIQUID_TRADE_CONTEXT` Return immutable funding and leverage context for one closed Hyperliquid trade using the composite key from the trades action. Use funding_status to distinguish a real zero from unavailable funding history; leverage fields may be omitted when the completed-trade source has no value. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `symbol` | string | Yes | Hyperliquid perpetual market ID, including the builder prefix for a HIP-3 market. | | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported. | | `direction` | string ("long" | "short") | Yes | Opening direction of the closed trade episode. | | `open_time` | integer | Yes | Episode open time as Unix seconds, copied from the matching trade returned by the Hyperliquid trades action. | | `close_time` | integer | Yes | Episode close time as Unix seconds, copied from the matching trade returned by the Hyperliquid trades action. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Closed Trades Aggregate **Slug:** `SURF_GET_HYPERLIQUID_TRADES_AGGREGATE` Aggregate a wallet's closed Hyperliquid trades by UTC day, symbol, direction, notional-size tier, or holding-time tier. Returns server-side P&L, fee, funding-coverage, win-rate, and volume rollups in one bounded, non-paginated response; use daily groups for a realized equity curve. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | Inclusive close-time window end as Unix seconds, an ISO 8601 date-time, or a UTC date; a date includes that whole day. Defaults to now. | | `dex` | string ("main_dex" | "xyz" | "flx" | "vntl" | "hyna" | "km" | "abcd" | "cash" | "para" | "mkts") | No | Market scope. Use main_dex for the native market or a builder-market name; omit to aggregate across all markets. | | `from_` | string | No | Inclusive close-time window start as Unix seconds, an ISO 8601 date-time, or a UTC date. Omit for full history. | | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported. | | `group_by` | string ("day" | "symbol" | "direction" | "size_bucket" | "hold_bucket") | No | Rollup dimension: UTC day, market symbol, long/short direction, notional-size bucket, or holding-time bucket. | | `fill_gaps` | boolean | No | For a daily aggregation, emit zero rows for no-trade UTC days. Requires from_ to bound the dense calendar. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Open Interest History **Slug:** `SURF_GET_KALSHI_OPEN_INTEREST` Return daily open-interest history for one Kalshi market over a selected time window. Data refreshes approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ticker` | string | Yes | Kalshi market ticker. Discover valid tickers with the Kalshi markets or prediction-market search actions. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | History window. This endpoint returns daily points and does not accept an interval parameter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Price History **Slug:** `SURF_GET_KALSHI_PRICES` Return hourly or daily OHLC price history for one Kalshi market, or the latest price from recent trades. Surf refreshes this data about every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ticker` | string | Yes | Kalshi market ticker. Discover valid tickers with the Kalshi markets or prediction-market search actions. | | `interval` | string ("1h" | "1d" | "latest") | No | Point granularity: `1h` for hourly OHLC, `1d` for daily OHLC, or `latest` for the most recent trade price. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | History window. Ignored when `interval` is `latest`; distinct from the interval bucket size. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Volume History **Slug:** `SURF_GET_KALSHI_VOLUMES` Return daily notional trading-volume history for one Kalshi market over a selected time window. Surf refreshes this data about every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ticker` | string | Yes | Kalshi market ticker. Discover valid tickers with the Kalshi markets or prediction-market search actions. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | History window: `7d`, `30d`, `90d`, `180d`, or `1y`. This endpoint returns daily points and does not accept an interval parameter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### ETF Flow History **Slug:** `SURF_GET_MARKET_ETF` Return daily spot ETF flow history for BTC, ETH, XRP, SOL, or HYPE, including net USD flow, closing token price, settlement status, and per-ticker flow breakdowns. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. | | `order` | string ("asc" | "desc") | No | Sort direction for the returned daily flow rows. | | `symbol` | string ("BTC" | "ETH" | "XRP" | "SOL" | "HYPE") | Yes | Underlying token symbol for the spot ETF flow history. | | `sort_by` | string ("flow_usd" | "timestamp") | No | Field used to sort the returned daily flow rows. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fear & Greed Index History **Slug:** `SURF_GET_MARKET_FEAR_GREED` Return Bitcoin Fear and Greed Index history, including each 0-100 index value, its classification, and the Bitcoin price at that time. Results are sorted newest first and can be bounded by a date or Unix-time range. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Futures Market Overview **Slug:** `SURF_GET_MARKET_FUTURES` Return a single ranked snapshot of futures market data across all tracked tokens, including open interest, funding rate, long/short ratio, and 24-hour volume. The endpoint returns the complete list and does not support symbol filtering or pagination. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `order` | string ("asc" | "desc") | No | Sort direction for the ranked futures snapshot. | | `sort_by` | string ("open_interest" | "funding_rate" | "volume_24h" | "long_short_ratio") | No | Futures metric used to rank the returned tokens. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Liquidation Chart **Slug:** `SURF_GET_MARKET_LIQUIDATION_CHART` Return time-bucketed aggregate long- and short-side liquidation volumes for a token on a specific exchange and interval. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. | | `limit` | integer | No | Maximum chart points to return (1-4500). | | `symbol` | string | Yes | Token ticker symbol. | | `exchange` | string ("Binance" | "OKX" | "Bybit" | "Bitget" | "Hyperliquid" | "Gate" | "HTX" | "Bitmex" | "Bitfinex" | "CoinEx" | "Aster" | "Lighter") | No | Exchange whose liquidation data should be aggregated. | | `interval` | string ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "4h" | "6h" | "8h" | "12h" | "1d" | "1w") | No | Bucket size for each liquidation chart point. This endpoint does not accept `time_range`; use `from_` and `to` to bound the series. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Liquidation by Exchange **Slug:** `SURF_GET_MARKET_LIQUIDATION_EXCHANGE_LIST` Return a single ranked snapshot of total, long-side, and short-side liquidation volumes by exchange for a token and aggregation window. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `order` | string ("asc" | "desc") | No | Sort direction for the ranked exchange snapshot. | | `symbol` | string | No | Token ticker symbol whose liquidations should be aggregated. | | `sort_by` | string ("liquidation_usd" | "long_liquidation_usd" | "short_liquidation_usd") | No | Liquidation volume field used to rank exchanges. | | `time_range` | string ("1h" | "4h" | "12h" | "24h") | No | Window to aggregate into one snapshot. This endpoint accepts time_range rather than interval and does not return a time series. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### On-Chain Indicator **Slug:** `SURF_GET_MARKET_ONCHAIN_INDICATOR` Return daily on-chain indicator history for BTC or ETH, including NUPL, SOPR, MVRV, Puell Multiple, NVM, NVT, NVT Golden Cross, and exchange-flow metrics. Responses are capped at about 100 points; when meta.has_more is true, split the requested date range into smaller windows. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. Defaults to today; the maximum range is 365 days. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. Defaults to 90 days ago; the maximum range is 365 days. | | `metric` | string ("nupl" | "sopr" | "mvrv" | "puell-multiple" | "nvm" | "nvt" | "nvt-golden-cross" | "exchange-flows/inflow" | "exchange-flows/outflow" | "exchange-flows/netflow" | "exchange-flows/reserve") | Yes | On-chain metric to return. Exchange-flow metrics include the flow direction after `exchange-flows/`. | | `symbol` | string ("BTC" | "ETH") | Yes | Token ticker symbol whose on-chain indicator history to return. | | `exchange` | string ("all_exchange" | "spot_exchange" | "derivative_exchange" | "coinbase_prime" | "binance" | "coinbase_advanced" | "okx" | "kraken" | "bybit" | "bitstamp" | "gemini" | "bitget" | "kucoin" | "bitfinex" | "gate_io" | "deribit" | "mexc" | "htx_global" | "bitflyer" | "coinone" | "bithumb" | "upbit" | "hashkey_exchange") | No | Curated exchange filter for exchange-flow metrics. Use the exchange-flow exchange-list action to discover labels. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Options Market Data **Slug:** `SURF_GET_MARKET_OPTIONS` Return options market data for one supported token, including open interest, 24-hour volume, put/call ratio, and max pain price by exchange. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `order` | string ("asc" | "desc") | No | Sort direction for the exchange rows. | | `symbol` | string ("BTC" | "ETH" | "SOL" | "XRP" | "BNB" | "DOGE" | "ADA" | "AVAX") | Yes | Underlying token symbol whose options market data should be returned. | | `sort_by` | string ("open_interest" | "volume_24h") | No | Options metric used to sort the exchange rows. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Price History **Slug:** `SURF_GET_MARKET_PRICE` Return historical prices for one listed token in a selected quote currency. Use a predefined window or paired custom bounds; Surf automatically chooses 5-minute, hourly, or daily granularity based on the range. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of a custom range as Unix seconds or YYYY-MM-DD. Must be used with `from_`; together they override `time_range`. | | `from_` | string | No | Start of a custom range as Unix seconds or YYYY-MM-DD. Must be used with `to`; together they override `time_range`. | | `symbol` | string | Yes | Single token ticker symbol, such as BTC, ETH, or SOL. Multiple symbols are not supported. | | `currency` | string | No | Quote currency, such as `usd`, `eur`, or `btc`. | | `time_range` | string ("1d" | "7d" | "14d" | "30d" | "90d" | "180d" | "365d" | "max") | No | Historical window. Surf chooses the point granularity automatically. Ignored when both `from_` and `to` are set. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Technical Indicator **Slug:** `SURF_GET_MARKET_PRICE_INDICATOR` Return a technical indicator for a trading pair on a given exchange and candlestick interval. Omit from_ and to for the latest value, or provide a time range for a bounded series. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. Defaults to the current time when from_ is set. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. Set this to return a time series instead of only the latest value. | | `symbol` | string | Yes | Trading pair such as BTC/USDT, or a bare token symbol such as BTC. | | `options` | object | No | Typed indicator-specific tuning. Use period for rsi, sma, ema, bbands, adx, atr, cci, dmi, stoch, or supertrend; stddev only for bbands; multiplier only for supertrend; and fast_period, slow_period, and signal_period only for macd. obv, vwap, and ichimoku have no options. | | `exchange` | string ("binance" | "bybit" | "coinbase" | "kraken") | No | Exchange from which to obtain the underlying price data. | | `interval` | string ("1m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "12h" | "1d" | "1w") | No | Candlestick interval used to calculate each indicator data point. | | `indicator` | string ("rsi" | "macd" | "ema" | "sma" | "bbands" | "stoch" | "adx" | "atr" | "cci" | "obv" | "vwap" | "dmi" | "ichimoku" | "supertrend") | Yes | Technical indicator to calculate for the requested trading pair. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Public Sale / Crowdsale **Slug:** `SURF_GET_MARKET_PUBLIC_SALE` Return public sale information for a project resolved by Surf UUID, name, or token symbol, including sale type, status, dates, token price, funds raised, supply allocation, launchpad, and all-time-high ROI. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `project_id` | string | No | Surf project UUID. At least one of `project_id` or `project_name` must be non-empty; prefer this exact identifier when available. | | `project_name` | string | No | Project name or token symbol used for entity resolution. At least one of `project_id` or `project_name` must be non-empty. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Generation Event **Slug:** `SURF_GET_MARKET_TGE` Return Token Generation Event status for a project resolved by Surf UUID, name, or token symbol, including the current status, last status-change time, and launch exchanges. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `project_id` | string | No | Surf project UUID. Provide `project_id` or `project_name`; both may be supplied. | | `project_name` | string | No | Project name or token symbol. Provide `project_id` or `project_name`; both may be supplied. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### News Article Detail **Slug:** `SURF_GET_NEWS_DETAIL` Return the full content and metadata of one news article by an ID obtained from Surf news feed or search results. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `id` | string | Yes | Article ID returned by Surf news feed or search results. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### DEX Protocol Activity **Slug:** `SURF_GET_ONCHAIN_DEX_ACTIVITY` Return active traders, trade count, and USD volume for one DEX protocol or router contract as either a total aggregate or a newest-first daily series. USD volume can lag by about three days; use enriched_ratio to assess completeness. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the range as Unix seconds or a YYYY-MM-DD date. Without from_, the selected time_range ends at this bound. | | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron") | Yes | Chain whose DEX activity to query. | | `from_` | string | No | Start of the range as Unix seconds or a YYYY-MM-DD date. With to, the range may span at most 90 days. | | `address` | string | No | Router or contract address measured as the transaction recipient. Provide exactly one of address or project. | | `project` | string | No | DEX project name, such as `uniswap`, `pancakeswap`, or `aerodrome`. Provide exactly one of project or address. | | `group_by` | string ("total" | "day") | No | Aggregation shape: total returns one aggregate and day returns a newest-first daily series. | | `time_range` | string ("1d" | "7d" | "30d" | "90d") | No | Look-back window, capped at 90 days. Explicit from_ or to bounds override this window. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Current Onchain Gas Price **Slug:** `SURF_GET_ONCHAIN_GAS_PRICE` Return the current gas price for one supported EVM chain in both wei and Gwei. Surf reads the latest value from the chain's eth_gasPrice JSON-RPC method. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "polygon" | "bsc" | "arbitrum" | "optimism" | "base" | "avalanche" | "fantom" | "linea" | "cyber") | Yes | EVM chain whose current gas price to retrieve. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### On-Chain Table Schema **Slug:** `SURF_GET_ONCHAIN_SCHEMA` Discover logical on-chain tables and columns before writing SQL or structured queries. Filter by table to include its bounded physical source metadata. Transfer-table amount values are decimal-adjusted display units; amount_raw contains the original base-unit value. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `table` | string | No | Logical table name in the agent database. Provide it to include bounded physical partition, ordering-key, and size metadata. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Asynchronous Blockchain SQL Job **Slug:** `SURF_GET_ONCHAIN_SQL_JOB` Return durable job status, elapsed time, ClickHouse progress counters, retry semantics, and result links for an asynchronous blockchain SQL job. Polling this action never starts another ClickHouse execution. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `job_id` | string | Yes | Asynchronous SQL job identifier. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Download Asynchronous Blockchain SQL Results **Slug:** `SURF_GET_ONCHAIN_SQL_JOB_RESULTS` Return a completed asynchronous blockchain SQL job's retained results as structured JSON or a downloadable CSV. Results remain available for 24 hours and are isolated to the authenticated tenant or user. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `format` | string ("json" | "csv") | No | Result representation: a structured JSON envelope or downloadable CSV. | | `job_id` | string | Yes | Asynchronous SQL job identifier. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Transaction Details by Hash **Slug:** `SURF_GET_ONCHAIN_TX` Look up one EVM transaction by chain and hash. Numeric transaction fields are returned as hexadecimal strings; request the labels enrichment to attach known sender and recipient entities. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `hash` | string | Yes | Transaction hash as 0x-prefixed hexadecimal. | | `chain` | string ("ethereum" | "polygon" | "bsc" | "arbitrum" | "optimism" | "base" | "avalanche" | "fantom" | "linea" | "cyber") | Yes | EVM chain on which to look up the transaction. | | `include` | string | No | Set to `labels` to include entity information for the sender and recipient addresses. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Open Interest History **Slug:** `SURF_GET_POLYMARKET_OPEN_INTEREST` Return daily open-interest history in USD for one Polymarket market over a selected time window. Data refreshes approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | History window. This endpoint returns daily points and does not accept an interval parameter. | | `condition_id` | string | Yes | Polymarket market condition identifier. Discover valid condition IDs with the Polymarket events or prediction-market search actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket OHLCV Candlesticks **Slug:** `SURF_GET_POLYMARKET_PRICE_OHLCV` Return OHLCV candlesticks for a Polymarket market for price-chart and bar visualizations. Each candle includes open, high, low, close, volume, and trade count. Use Polymarket price history instead for one price per interval. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_time` | integer | No | Window end as Unix seconds. Use 0 for the current time. Surf aligns cached requests to five-minute buckets. | | `interval` | integer | No | Candle interval in minutes, such as 1, 60, or 1440. | | `start_time` | integer | No | Window start as Unix seconds. Use 0 for no lower bound. Surf aligns cached requests to five-minute buckets. | | `condition_id` | string | Yes | Polymarket condition ID. Use prediction-market search to discover condition IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Price History **Slug:** `SURF_GET_POLYMARKET_PRICES` Return hourly or daily outcome-price history for one Polymarket market, or its latest price snapshot. Use Polymarket OHLCV instead for candlestick data. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `interval` | string ("1h" | "1d" | "latest") | No | Point granularity: `1h` for hourly points, `1d` for daily points, or `latest` for one most-recent snapshot. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | History window measured backward from now. Ignored when `interval` is `latest`; distinct from the interval bucket size. | | `condition_id` | string | Yes | Polymarket condition identifier. Discover condition IDs with the Polymarket markets or prediction-market search actions. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Volume History **Slug:** `SURF_GET_POLYMARKET_VOLUMES` Return aggregate Polymarket trading volume in USD and trade count as a time series for volume-trend analysis. Use Polymarket volume split for a YES/NO outcome-side breakdown. Surf refreshes this data about every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_time` | integer | No | History end as a Unix timestamp in seconds; an alternative to `time_range`. | | `interval` | string ("1h" | "1d") | No | Bucket size for each volume point: `1h` for hourly or `1d` for daily. Distinct from the history window. | | `token_id` | string | No | Polymarket outcome token identifier. Provide `token_id` or `condition_id`; both may be supplied. Surf resolves it to the market condition. | | `start_time` | integer | No | History start as a Unix timestamp in seconds; an alternative to `time_range`. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | History window measured backward from now: `7d`, `30d`, `90d`, `180d`, or `1y`. Distinct from the interval bucket size. | | `granularity` | string ("day" | "week" | "month" | "year" | "all") | No | Aggregation granularity to query daily buy/sell volume: `day`, `week`, `month`, `year`, or `all`. Use as an alternative to `interval`. | | `condition_id` | string | No | Polymarket market condition identifier. Provide `condition_id` or `token_id`; both may be supplied. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Volume Split (YES/NO) **Slug:** `SURF_GET_POLYMARKET_VOLUME_SPLIT` Return Polymarket trading volume split into YES and NO outcome sides for hourly, daily, or weekly intervals, including total volume and trade count. Use Polymarket volume history instead for aggregate volume without an outcome-side breakdown. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `end_time` | integer | No | Window end as Unix seconds. Use 0 for the current time. Surf aligns cached requests to five-minute buckets. | | `start_time` | integer | No | Window start as Unix seconds. Use 0 for no lower bound. Surf aligns cached requests to five-minute buckets. | | `granularity` | string ("hour" | "day" | "week") | No | Time bucket used to aggregate volume: hour, day, or week. | | `condition_id` | string | Yes | Polymarket condition ID. Use prediction-market search to discover condition IDs. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Aggregated Project Detail **Slug:** `SURF_GET_PROJECT_DETAIL` Return a crypto project's profile with selectable overview, token market, legacy tokenomics, funding, team, contract, social, and token-generation sections. Use the dedicated project DeFi metrics action for TVL, fees, revenue, volume, users, and per-chain metrics. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `x_id` | string | No | Numeric X account ID used to resolve its associated project. Provide project_id, project_name, x_id, or handle. | | `fields` | array | No | Project detail sections to include. | | `handle` | string | No | X handle without the @ prefix used to resolve its associated project. Provide project_id, project_name, x_id, or handle. | | `project_id` | string | No | Surf project UUID. Provide project_id, project_name, x_id, or handle. Prefer this exact identifier when available; it takes priority over project_name. | | `project_name` | string | No | Fuzzy project name used when an exact identifier is unavailable. Provide project_id, project_name, x_id, or handle. Ambiguous names may match an unexpected project. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Signal Detail **Slug:** `SURF_GET_SIGNAL_DETAIL` Return one project signal card by Surf token UUID or project slug, including its score, classified state, score dimensions, market data, and summaries. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `token_id` | string | No | Surf token UUID. Pass exactly one of `token_id` or `project_slug`. | | `time_range` | string ("24h" | "7d") | No | Window over which Surf computes the signal score. | | `project_slug` | string | No | Project slug. Pass exactly one of `token_id` or `project_slug`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Transfer Activity Summary **Slug:** `SURF_GET_TOKEN_TRANSFER_STATS` Return aggregate transfer activity for a token contract over a selected window, including transfer count, approximate unique senders and receivers, token amount, activity bounds, and USD-enrichment coverage. Set include=series for a newest-first daily breakdown. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron") | Yes | Chain where the token contract is deployed. | | `address` | string | Yes | Token contract address, not a ticker symbol. Use a 0x-prefixed address for EVM chains; Tron also accepts a base58 T-address. | | `include` | string | No | Set to `series` to include the newest-first daily transfer breakdown. | | `time_range` | string ("1d" | "7d" | "30d" | "90d") | No | Look-back window for the transfer summary, capped at 90 days. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Unlock Schedule **Slug:** `SURF_GET_TOKEN_UNLOCK_SCHEDULE` Return token unlock time-series with cumulative amounts, allocation breakdowns, total supply denominator, and unlocked-supply percentage. Look up by Surf project UUID or token symbol and optionally bound the date range. `unlock_amount` is already cumulative and must not be summed across rows. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. The current calendar month is used when the range is omitted. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. The current calendar month is used when the range is omitted. | | `symbol` | string | No | Token symbol such as `ARB`, `OP`, or `APT`. At least one of `project_id` or `symbol` is required. | | `project_id` | string | No | Surf project UUID. At least one of `project_id` or `symbol` is required. Prefer this when available from a previous response; it takes priority over `symbol`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Aggregated Wallet Detail **Slug:** `SURF_GET_WALLET_DETAIL` Return a wallet's cross-chain portfolio with selectable balance, token, label, NFT, and approval sub-resources, plus its per-chain USD breakdown. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "polygon" | "bsc" | "avalanche" | "arbitrum" | "optimism" | "fantom" | "base" | "solana") | No | Chain filter for tokens, NFTs, and approvals. When omitted, Surf queries all EVM chains for a 0x address or Solana for a base58 address. | | `fields` | array | No | Sub-resources to include. active_chains is always returned. approvals is opt-in and triggers additional upstream calls. | | `address` | string | Yes | Wallet address as 0x-prefixed EVM hexadecimal or Solana base58. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Get Wallet Labels Batch **Slug:** `SURF_GET_WALLET_LABELS_BATCH` Return entity names, entity types, and labels for up to 100 wallet addresses in one request. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `addresses` | array | Yes | Wallet addresses to look up, with no more than 100 per request. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Wallet Net Worth History **Slug:** `SURF_GET_WALLET_NET_WORTH` Return about 24 hours of total wallet net worth in USD at five-minute intervals for one EVM address. The time window is fixed and cannot be customized. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `address` | string | Yes | Raw 0x-prefixed EVM wallet address. ENS names and Solana addresses are not supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Web Page Fetch **Slug:** `SURF_GET_WEB_FETCH` Fetch one web page and convert its content to clean markdown, optionally limiting extraction, removing elements, or waiting for dynamic content with CSS selectors. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | Yes | URL of the web page to fetch and convert to markdown. | | `timeout` | integer | No | Maximum time in milliseconds to wait for the page fetch. | | `remove_selector` | string | No | CSS selector for page elements to remove before conversion. | | `target_selector` | string | No | CSS selector that limits extraction to matching page content. | | `wait_for_selector` | string | No | CSS selector to wait for before extracting the page content. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### X Tweets by IDs **Slug:** `SURF_GET_X_TWEETS_BY_IDS` Return normalized X posts by numeric ID. Authentication is required. Each request costs at least 7 credits per unique requested ID; the actual cost reflects plan and tenant pricing. Repeated IDs are billed and looked up once. Unavailable IDs are billed and omitted from data; returned posts preserve first-input order. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `ids` | array | Yes | Numeric tweet IDs, from 1 to 100 values. Each ID must contain 1 to 19 digits without leading zeros. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Airdrop Activities **Slug:** `SURF_LIST_AIRDROP_ACTIVITIES` Return one page of airdrop activities with project, reward, status, fundraising, and social metrics. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Airdrop activities to return in this page (1-100). | | `offset` | integer | No | Number of airdrop activities to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### ETF Holdings **Slug:** `SURF_LIST_EQUITY_ETF_HOLDINGS` Return one page from a stored ETF or index-fund portfolio snapshot plus its immediately previous snapshot, ordered newest to oldest. Available quarterly periods describe the stored holdings history. Set offset explicitly for another page; total_holdings is unfiltered and does not establish whether filtered results continue. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `as_of` | string | No | Select the composition effective on or before this YYYY-MM-DD date; the response also includes its immediately previous snapshot. | | `limit` | integer | No | Maximum holdings to return. | | `offset` | integer | No | Number of filtered holdings to skip. Set this explicitly to request another page; total_holdings is unfiltered and cannot prove continuation when asset_class is set. | | `symbol` | string | Yes | US-listed ETF or index-fund ticker symbol. | | `asset_class` | string ("equity" | "bond") | No | Filter holdings by instrument type. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity SEC Filings **Slug:** `SURF_LIST_EQUITY_FILINGS` Return one page of verified periodic SEC filings for a US equity, including canonical filing metadata, document URLs, statement coverage, and provenance. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `offset` | integer | No | Number of matching filings to skip on the first page. | | `symbol` | string | Yes | US equity ticker symbol. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Listings **Slug:** `SURF_LIST_EQUITY_LISTINGS` Return one page of current verified active stock listings for the issuer resolved from the requested ticker. Ticker alone is not treated as a durable listing identity. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `offset` | integer | No | Number of matching listings to skip on the first page. | | `symbol` | string | Yes | Ticker used to resolve the issuer whose current verified stock listings are returned. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Equity Segment Financials **Slug:** `SURF_LIST_EQUITY_SEGMENTS` Return one page of provider-reported product and operating or geographic segment facts for a US-listed equity. Provider labels and missing-value status are preserved; values are not added across incompatible dimensions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `label` | string | No | Optional provider-reported segment label to match. | | `limit` | integer | No | Maximum number of segment facts to return in this page (1-100). | | `offset` | integer | No | Number of matching segment facts to skip on the first page. | | `period` | string ("quarterly" | "annual") | No | Financial period represented by the segment facts. | | `symbol` | string | Yes | US equity ticker symbol. | | `end_date` | string | No | Inclusive latest period end in YYYY-MM-DD format. | | `start_date` | string | No | Inclusive earliest period start in YYYY-MM-DD format. | | `metric_code` | string | No | Optional normalized financial metric code to match. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `dimension_type` | string | No | Optional provider dimension key, such as product or segment. | | `statement_type` | string ("income" | "balance_sheet" | "cash_flow") | No | Optional financial statement family to return. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Historical Candles **Slug:** `SURF_LIST_EXCHANGE_CANDLES` Return one page of persisted OHLCV candles for a covered Bithumb, Upbit, HashKey, bitFlyer, Coinone, or Korbit spot market. Results are ordered newest first. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a date string. | | `pair` | string | Yes | Trading pair in base/quote form. | | `from_` | string | No | Start of the time range as Unix seconds or a date string. | | `limit` | integer | No | Candles to return in this page (1-300). Weekly candles allow up to 300 rows; intraday intervals are capped at 100 by Surf. | | `offset` | integer | No | Number of matching candles to skip on the first page. | | `exchange` | string ("bithumb" | "upbit" | "hashkey" | "bitflyer" | "coinone" | "korbit") | Yes | Exchange identifier. | | `interval` | string ("5m" | "4h" | "1w") | No | Candle interval. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `include_synthetic` | boolean | No | Whether to include carry-forward candles for no-trade intervals. Set false to return raw exchange-only candles. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Market Coverage **Slug:** `SURF_LIST_EXCHANGE_COVERAGE` Return one page of covered spot markets on Bithumb, Upbit, HashKey, bitFlyer, Coinone, and Korbit with ticker metrics, candle availability, technical score, and data status. Inspect data_status and data_actionability before using sparse or stale market data. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort order. | | `query` | string | No | Free-text search over pair, base currency, or quote currency. | | `quote` | string | No | Quote currency filter. | | `offset` | integer | No | Number of matching markets to skip on the first page. | | `status` | string ("active" | "inactive") | No | Market status filter. | | `sort_by` | string ("pair" | "price" | "change_24h" | "volume_24h" | "technical_score" | "latest_candle_at" | "status") | No | Field used to sort matching markets. | | `exchange` | string ("bithumb" | "upbit" | "hashkey" | "bitflyer" | "coinone" | "korbit") | No | Exchange identifier. Omit to return all supported exchanges. | | `data_status` | string ("covered" | "official_empty_all" | "official_empty_ticker" | "official_empty_5m" | "official_empty_weekly" | "stale_gt_7d" | "stale_30m_to_7d" | "recent_but_lt_min_ta_candles" | "missing_4h" | "missing_latest_ta") | No | Market data coverage status filter. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fund Portfolio **Slug:** `SURF_LIST_FUND_PORTFOLIO` Return one page of a fund's investment rounds, sorted by the selected field. A project may appear more than once when the fund participated in multiple rounds. Prefer an exact fund id over a fuzzy name query. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort order. | | `offset` | integer | No | Number of matching investments to skip on the first page. | | `fund_id` | string | No | Surf fund UUID. For the first page, provide fund_id or fund_name; prefer this exact identifier because it takes priority over fund_name. Omit on continuation calls that provide next_cursor. | | `is_lead` | boolean | No | Filter by lead investor status. Omit to include all investments. | | `sort_by` | string ("invested_at" | "recent_raise" | "total_raise") | No | Field used to sort matching investments. | | `fund_name` | string | No | Fuzzy fund name search. For the first page, provide fund_id or fund_name; use this only when fund_id is unavailable. Omit on continuation calls that provide next_cursor. Ambiguous names may return unexpected results. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page without repeating fund_id or fund_name. | | `invested_after` | integer | No | Only include investments at or after this Unix timestamp in seconds. | | `invested_before` | integer | No | Only include investments before this Unix timestamp in seconds. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fund Ranking **Slug:** `SURF_LIST_FUND_RANKING` Return one page of crypto VC funds ranked by fund tier or number of invested projects, including up to five top portfolio projects per fund. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `metric` | string ("tier" | "portfolio_count") | Yes | Ranking metric: `tier` ranks lower tiers first; `portfolio_count` ranks by number of invested projects. | | `offset` | integer | No | Number of ranked funds to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fills **Slug:** `SURF_LIST_HYPERLIQUID_FILLS` Return one page of a wallet's individual Hyperliquid fills with realized PnL, fees, liquidity direction, and an opaque cursor. Use ascending order with from_ and follow next_cursor for complete history; descending order is a recent capped feed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | Inclusive window end as Unix seconds or a date; defaults to now. | | `from_` | string | No | Window start as Unix seconds or a date. Required for an ascending complete-history walk. | | `limit` | integer | No | Fills to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction. Descending returns the recent capped feed; ascending with from_ supports a complete-history cursor walk. | | `to_ms` | integer | No | Exclusive window end in Unix milliseconds for descending pagination. Pair it with to_fill_id to avoid skipping fills at the same millisecond. | | `cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged; do not combine it with from_, to, to_ms, or to_fill_id. | | `symbol` | string | No | Exact market filter, such as xyz:GOLD. Filtering may produce an empty page that still has a continuation cursor. | | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported. | | `to_fill_id` | string | No | Fill identifier paired with to_ms for lossless descending pagination through fills sharing one millisecond. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Trader Leaderboard **Slug:** `SURF_LIST_HYPERLIQUID_LEADERBOARD` Return one page of Hyperliquid traders ranked by PnL, win rate, or volume, with trade activity, account age, human-likeness, and market filters. Leaderboard PnL includes funding and must not be treated as equivalent to the funding-excluded PnL from Hyperliquid performance or trade actions. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `dex` | string ("main_dex" | "xyz" | "flx" | "vntl" | "hyna" | "km" | "abcd" | "cash" | "para" | "mkts") | No | Market to rank within. Omit or use `main_dex` for Hyperliquid's native market; otherwise select a builder market. | | `limit` | integer | No | Traders to return in this page (1-100). | | `offset` | integer | No | Number of ranked traders to skip on the first page. | | `sort_by` | string ("total_pnl" | "win_rate" | "volume_traded") | No | Metric used to rank traders in descending order. | | `min_trades` | integer | No | Minimum trades in the selected window. Use 0 for no trade-count filter. | | `time_range` | string ("1d" | "7d" | "30d" | "90d" | "all") | No | Performance window. `all` includes data from 2025-08-01 onward. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `min_days_active` | integer | No | Minimum distinct active days in the selected window. Use 0 to disable. | | `min_human_score` | integer | No | Minimum human-likeness score from 0 to 100. Use 0 to disable. | | `min_account_age_days` | integer | No | Minimum account age in days. Use 0 to disable this filter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Closed Trades **Slug:** `SURF_LIST_HYPERLIQUID_TRADES` Return one page of a wallet's closed Hyperliquid position lifecycles, newest close first, with entry and exit prices, size, hold time, fees, and realized PnL. net_pnl excludes funding; inspect funding_pnl and funding_status separately. Follow next_cursor for older trades. Use Closed Trades Aggregate for symbol, direction, or market-scoped rollups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | Inclusive first-page window end as Unix seconds, an ISO 8601 date-time, or a UTC date. A date includes that whole day; defaults to now. | | `from_` | string | No | First-page window start as Unix seconds, an ISO 8601 date-time, or a UTC date. Omit for full history. | | `limit` | integer | No | Closed trades to return in this page (1-100). | | `cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged with the same address and do not combine it with from_ or to. | | `address` | string | Yes | Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Events **Slug:** `SURF_LIST_KALSHI_EVENTS` Return one page of Kalshi events with their nested markets, optionally filtered by event ticker. Omit event_ticker to browse top active events by volume. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Events to return in this page (1-100). | | `offset` | integer | No | Number of matching events to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `event_ticker` | string | No | Kalshi event ticker. Omit to return the top active events by volume; use prediction-market search to discover a ticker. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Markets **Slug:** `SURF_LIST_KALSHI_MARKETS` Return one page of Kalshi markets with status, payout type, volume, and open interest. Filter by an exact market ticker, or omit it to browse top active markets by volume. Data refreshes approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Markets to return in this page (1-100). | | `offset` | integer | No | Number of matching markets to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `market_ticker` | string | No | Kalshi market ticker. Omit to return top active markets by volume; use prediction-market search to discover tickers. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Orderbook History **Slug:** `SURF_LIST_KALSHI_ORDERBOOKS` Return one page of historical YES-side bid and ask snapshots for a Kalshi market. Timestamps are Unix milliseconds and prices are cents. Follow next_cursor with pagination_key to retrieve additional snapshots. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of orderbook snapshots to return in this page (1-200). | | `ticker` | string | Yes | Kalshi market ticker whose historical orderbook snapshots to return. | | `end_time` | integer | No | End time in Unix milliseconds. Omit or pass 0 to use the current time. | | `start_time` | integer | No | Start time in Unix milliseconds. Omit or pass 0 to use seven days ago. | | `pagination_key` | string | No | Base64 continuation key returned as next_cursor by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Kalshi Trades **Slug:** `SURF_LIST_KALSHI_TRADES` Return one page of real-time individual trades for a Kalshi market, with taker side, outcome prices, notional volume, and timestamp. Filter by side, minimum notional, or time range, and follow next_cursor for more trades. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. | | `limit` | integer | No | Trades to return in this page (1-500). | | `order` | string ("asc" | "desc") | No | Sort matching trades in ascending or descending order. | | `offset` | integer | No | Number of matching trades to skip on the first page. | | `ticker` | string | Yes | Kalshi market ticker. Use the Kalshi markets or prediction-market search actions to discover valid tickers. | | `sort_by` | string ("timestamp" | "notional_volume_usd") | No | Field used to sort matching trades. | | `min_amount` | integer | No | Minimum trade notional in USD; each contract has $1 notional value. | | `taker_side` | string ("yes" | "no") | No | Return only trades whose taker bought the yes or no side. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Flow Exchanges **Slug:** `SURF_LIST_MARKET_EXCHANGE_FLOW_EXCHANGES` Return one page of Surf's curated aggregate and high-coverage individual exchange filters for BTC or ETH exchange-flow metrics. Use a returned symbol as the exchange parameter for exchange-flow metrics in the market on-chain indicator action. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `offset` | integer | No | Number of exchange filters to skip on the first page. | | `symbol` | string ("BTC" | "ETH") | Yes | Token ticker symbol whose curated exchange-flow filters to return. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Large Liquidation Orders **Slug:** `SURF_LIST_MARKET_LIQUIDATION_ORDER` Return one offset page of individual large liquidation orders above a USD threshold. The provider exposes a bounded recent window; after its offset pages are exhausted, page backward by setting to to the oldest returned timestamp plus one and de-duplicating on order_id. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | Exclusive range end as Unix seconds or a date string. To continue beyond the bounded recent window, set this to the oldest returned timestamp plus one and de-duplicate on order_id. | | `side` | string ("long" | "short") | No | Liquidation side to return. Omit to return both long and short orders. | | `from_` | string | No | Inclusive range start as Unix seconds or a date string. | | `limit` | integer | No | Liquidation orders to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction. | | `offset` | integer | No | Number of matching orders to skip on the first page. | | `symbol` | string | No | Base token ticker to match, such as BTC or ETH. | | `sort_by` | string ("usd_value" | "timestamp" | "price") | No | Liquidation-order field used to sort the results. | | `exchange` | string ("Binance" | "OKX" | "Bybit" | "Bitget" | "Hyperliquid" | "Gate" | "HTX" | "Bitmex" | "Bitfinex" | "CoinEx" | "Aster" | "Lighter") | No | Exchange on which the liquidation occurred. | | `min_amount` | string | No | Minimum liquidated position size in USD. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next offset page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Exchange Listing Events **Slug:** `SURF_LIST_MARKET_LISTINGS` Return one page of historical exchange listing and delisting events, filtered by date range and optionally by token, exchange, product, or event type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the event date range. Defaults to the current time. | | `type` | string ("listing" | "delisting" | "cancelled" | "advanced" | "postponed") | No | Listing-event type to return. | | `from_` | string | Yes | Start of the event date range as YYYY-MM-DD or an ISO 8601 timestamp. | | `limit` | integer | No | Listing events to return in this page (1-100). | | `offset` | integer | No | Number of matching listing events to skip on the first page. | | `symbol` | string | No | Token ticker symbol used to filter listing events. | | `product` | string ("spot" | "margin" | "perp" | "pre_market_perp" | "all") | No | Exchange product type to return, or all product types. | | `exchange` | string | No | Exchange name used to filter listing events. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Rankings **Slug:** `SURF_LIST_MARKET_RANKING` Return one page of tokens ranked by market capitalization, 24-hour price change, or 24-hour trading volume, optionally filtered by token category. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Ranked tokens to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction: descending (highest first) or ascending (lowest first). | | `offset` | integer | No | Number of ranked tokens to skip on the first page. | | `sort_by` | string ("market_cap" | "change_24h" | "volume_24h") | No | Field used to rank tokens: market capitalization, 24-hour price change percentage, or 24-hour trading volume. | | `category` | string ("MEME" | "AI" | "AI_AGENTS" | "L1" | "L2" | "DEFI" | "GAMING" | "STABLECOIN" | "RWA" | "DEPIN" | "SOL_ECO" | "BASE_ECO" | "LST") | No | Token category used to filter the ranking. Omit to include all categories. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cross-Platform Daily Comparison (Polymarket <> Kalshi) **Slug:** `SURF_LIST_MATCHING_MARKET_DAILY` Return one page of daily volume and open-interest comparisons for a specific matched Polymarket and Kalshi market pair. Use matching-market pairs to discover the required identifiers first. Polymarket values are in USD; Kalshi values are in contracts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Daily comparison rows to return in this page (1-10000). | | `offset` | integer | No | Number of daily comparison rows to skip on the first page. | | `time_range` | string ("1d" | "7d" | "30d" | "90d" | "180d" | "1y" | "all") | No | Window of daily data to return. Buckets are fixed at one day; this endpoint does not accept an interval parameter. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `kalshi_market_ticker` | string | Yes | Kalshi market ticker for the matched pair. | | `polymarket_condition_id` | string | Yes | Polymarket condition ID for the matched pair. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Cross-Platform Prediction Market Matcher **Slug:** `SURF_LIST_MATCHING_MARKET_PAIRS` Return one page of matching Polymarket and Kalshi markets with match confidence, activity, volume, current probabilities, and price spread. Filter by category, match type, confidence, or a specific market ID; sort by spread_pct to find the widest current spreads. Data refreshes approximately every five minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Matching pairs to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Ascending or descending sort order. | | `offset` | integer | No | Number of matching pairs to skip on the first page. | | `sort_by` | string ("confidence" | "polymarket_volume" | "kalshi_volume" | "spread_pct") | No | Field used to sort matching pairs. | | `category` | string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports") | No | Prediction-market category to match across platforms. | | `match_type` | string ("exact" | "related") | No | Return exact or related cross-platform market matches. | | `active_only` | boolean | No | Whether to return only pairs where both markets are currently active. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `min_confidence` | integer | No | Minimum match confidence score from 0 through 100. | | `kalshi_market_ticker` | string | No | Kalshi market ticker whose Polymarket counterpart should be found. | | `polymarket_condition_id` | string | No | Polymarket condition ID whose Kalshi counterpart should be found. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Crypto News Feed **Slug:** `SURF_LIST_NEWS_FEED` Return one page of crypto news from major sources, optionally filtered by publisher, project, or publication time. Use an article ID with the news detail action to fetch full content. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | Return articles published on or before this time, expressed as Unix seconds or a date string. | | `from_` | string | No | Return articles published on or after this time, expressed as Unix seconds or a date string. | | `limit` | integer | No | Articles to return in this page (1-50). | | `offset` | integer | No | Number of matching articles to skip on the first page. | | `source` | string ("coindesk" | "cointelegraph" | "theblock" | "decrypt" | "dlnews" | "blockbeats" | "bitcoincom" | "coinpedia" | "ambcrypto" | "cryptodaily" | "cryptopotato" | "phemex" | "panews" | "odaily" | "tradingview" | "chaincatcher" | "techflow") | No | News source used to filter articles. | | `sort_by` | string ("recency" | "trending") | No | Article order: recency returns newest first; trending is currently a deterministic newest-first alias. | | `projects` | array | No | Project names used to filter articles. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Bridge Protocol Ranking **Slug:** `SURF_LIST_ONCHAIN_BRIDGE_RANKING` Return one page of bridge protocols ranked by USD transfer volume over a selected time range, including transfer counts. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Bridge protocols to return in this page (1-100). | | `offset` | integer | No | Number of ranked bridge protocols to skip on the first page. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y" | "all") | No | Window over which to aggregate bridge volume. Returns one ranked snapshot, not a time series. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Yield Pool Ranking **Slug:** `SURF_LIST_ONCHAIN_YIELD_RANKING` Return one page of individual DeFi yield pools ranked by APY or TVL, optionally filtered by protocol. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Yield pools to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction: descending (highest first) or ascending (lowest first). | | `offset` | integer | No | Number of ranked yield pools to skip on the first page. | | `project` | string | No | Protocol name to filter by, such as lido, aave, or uniswap. | | `sort_by` | string ("apy" | "tvl_usd") | No | Ranking metric. APY ranking includes only pools with at least $100,000 in TVL. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Events **Slug:** `SURF_LIST_POLYMARKET_EVENTS` Return one page of Polymarket events with aggregated status and volume plus their nested markets and outcomes, filtered by event slug. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Events to return in this page (1-100). | | `offset` | integer | No | Number of matching events to skip on the first page. | | `event_slug` | string | Yes | Polymarket event slug for a multi-outcome question. Use prediction-market search to discover event slugs; use Polymarket markets for a single Yes/No market slug. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Leaderboard **Slug:** `SURF_LIST_POLYMARKET_LEADERBOARD` Return one page of Polymarket traders ranked by realized PnL, trading volume, or trade count, including aggregate position outcomes. Data refreshes approximately every five minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Traders to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction: descending (highest first) or ascending (lowest first). | | `offset` | integer | No | Number of ranked traders to skip on the first page. | | `sort_by` | string ("pnl" | "volume" | "trade_count") | No | Metric used to rank traders: realized PnL, volume, or trade count. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Markets **Slug:** `SURF_LIST_POLYMARKET_MARKETS` Return one page of Polymarket markets with outcomes, status, volume, and condition identifiers, filtered by market slug. Use condition_id with the Polymarket prices action for current prices. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Markets to return in this page (1-100). | | `offset` | integer | No | Number of matching markets to skip on the first page. | | `market_slug` | string | Yes | Polymarket market slug for a single Yes/No market. Use prediction-market search to discover market slugs; use Polymarket events for a multi-outcome question. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Orderbook History **Slug:** `SURF_LIST_POLYMARKET_ORDERBOOKS` Return one page of historical bid and ask depth snapshots for a Polymarket token. Timestamps are Unix milliseconds and prices range from 0 to 1. Follow next_cursor with pagination_key to retrieve additional snapshots. Surf refreshes this data approximately every five minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Maximum number of orderbook snapshots to return in this page (1-200). | | `end_time` | integer | No | End time in Unix milliseconds. Omit or pass 0 to use the current time. | | `token_id` | string | Yes | Polymarket token identifier whose historical orderbook snapshots to return. | | `start_time` | integer | No | Start time in Unix milliseconds. Omit or pass 0 to use seven days ago. | | `pagination_key` | string | No | Base64 continuation key returned as next_cursor by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Wallet Positions **Slug:** `SURF_LIST_POLYMARKET_POSITIONS` Return one page of open Polymarket positions for a specific proxy wallet, including market identifiers, share size, valuation, and profit and loss. Surf refreshes this data approximately every 30 minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Positions to return in this page (1-100). | | `offset` | integer | No | Number of matching positions to skip on the first page. | | `address` | string | Yes | Polymarket proxy wallet address whose open positions to return. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Smart Money **Slug:** `SURF_LIST_POLYMARKET_SMART_MONEY` Return one page of Polymarket smart-wallet analytics. The positioning view aggregates bullish or bearish direction and conviction by market; the trades view returns individual trades of at least $10,000 with wallet metadata. Surf refreshes this data approximately every five minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End time as Unix seconds or a date string. Applies only to the trades view. | | `view` | string ("positioning" | "trades") | No | Result view: positioning aggregates smart-wallet direction by market; trades returns individual trades of at least $10,000 with wallet metadata. | | `from_` | string | No | Start time as Unix seconds or a date string. Applies only to the trades view. | | `limit` | integer | No | Smart-money records to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction. | | `offset` | integer | No | Number of matching records to skip on the first page. | | `sort_by` | string ("smart_wallets_involved" | "smart_buy_volume_usd" | "smart_sell_volume_usd" | "amount_usd" | "block_time") | No | Field used to sort the selected view. | | `category` | string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports") | No | Surf-curated market category to filter by. | | `direction` | string ("bullish" | "bearish" | "neutral") | No | Net smart-money direction filter. Applies only to the positioning view. | | `whale_tier` | string ("whale" | "large" | "mega") | No | Trade-size tier filter. Applies only to the trades view. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `condition_id` | string | No | Polymarket condition identifier to filter by. Omit to browse all markets. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Polymarket Trades **Slug:** `SURF_LIST_POLYMARKET_TRADES` Return one page of Polymarket trades or wallet activity, filtered by market, wallet, outcome, minimum amount, or time range. Use type=redemption for splits, merges, and redemptions, or type=all for every activity type. Surf refreshes this data approximately every five minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. | | `type` | string ("trade" | "redemption" | "all") | No | Activity type: trade returns spot trades; redemption returns splits, merges, and redemptions; all returns every activity type. Address is required for redemption and all. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. | | `limit` | integer | No | Activity records to return in this page (1-500). | | `offset` | integer | No | Number of matching activity records to skip on the first page. | | `address` | string | No | Wallet address used to return activity where it is the maker or taker. Provide condition_id or address on the first page; address is required when type is redemption or all. | | `sort_by` | string ("timestamp" | "notional_volume_usd") | No | Field used to sort matching activity. | | `min_amount` | number | No | Minimum trade amount in USD. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `condition_id` | string | No | Polymarket condition identifier used to filter activity by market. Provide condition_id or address on the first page. | | `outcome_label` | string ("Yes" | "No") | No | Return only activity for the Yes or No outcome. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Prediction Market Analytics **Slug:** `SURF_LIST_PREDICTION_MARKET_ANALYTICS` Return one page of prediction-market analytics with daily trends, top markets by open interest, momentum distribution, and per-market momentum signals. Omit category for platform-wide totals, and use platform for an exchange-specific view. Set offset explicitly to request another momentum-markets page because the response has no continuation metadata. Use prediction-market search instead to browse individual markets. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Momentum markets to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction for the momentum-markets page. | | `top_n` | integer | No | Number of markets to include in the top-markets ranking (1-50). | | `offset` | integer | No | Number of momentum markets to skip. Set this explicitly to request another page; the response does not provide a continuation offset. | | `sort_by` | string ("volume_7d" | "whale_flow_net_7d" | "price_change_7d" | "oi_change_7d") | No | Metric used to sort the momentum-markets page. | | `category` | string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports") | No | Prediction-market category to analyze. Omit for totals across all categories. | | `platform` | string ("polymarket" | "kalshi") | No | Prediction-market platform to analyze. Omit to combine both platforms. | | `time_range` | string ("7d" | "30d" | "90d" | "180d" | "1y") | No | Window for daily category trends. The bucket size is always one day; this endpoint does not accept an interval parameter. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Market Correlations **Slug:** `SURF_LIST_PREDICTION_MARKET_CORRELATIONS` Return one page of 30-day Pearson price-correlation pairs between Polymarket markets in one category. Results cover the top 100 markets by 7-day volume globally; lower-volume markets may have no correlation data. Filter by condition_id to find markets correlated with one market. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Correlation pairs to return in this page (1-100). | | `offset` | integer | No | Number of correlation pairs to skip on the first page. | | `category` | string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports") | Yes | Prediction-market category; correlations are within-category only. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `condition_id` | string | No | Return only pairs involving this Polymarket condition ID. | | `min_correlation` | number | No | Minimum absolute 30-day Pearson correlation coefficient. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Project AI News **Slug:** `SURF_LIST_PROJECT_AI_NEWS` Return one page of AI-generated news and signal analysis for a project identified by Surf UUID or fuzzy name. Results include price-analysis and funding signals; social and X-derived items are excluded by Surf. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `lang` | string ("en" | "zh" | "ja" | "kr") | No | Language for AI-generated content. | | `limit` | integer | No | News items to return in this page (1-50). | | `offset` | integer | No | Number of matching news items to skip on the first page. | | `project_id` | string | No | Surf project UUID. Prefer this identifier when available; it takes priority over project_name. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `project_name` | string | No | Fuzzy project name to use only when project_id is unavailable; ambiguous names may match an unexpected project. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Project DeFi Metrics **Slug:** `SURF_LIST_PROJECT_DEFI_METRICS` Return one page of historical metric points for a single DeFi protocol. Look up the protocol by exact Surf project UUID when available or by fuzzy name, then filter by metric, chain, and time range. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the time range as Unix seconds or a YYYY-MM-DD date. | | `chain` | string ("ethereum" | "polygon" | "bsc" | "avalanche" | "arbitrum" | "optimism" | "fantom" | "base" | "solana") | No | Blockchain on which to filter the protocol metric. | | `from_` | string | No | Start of the time range as Unix seconds or a YYYY-MM-DD date. | | `limit` | integer | No | Results to return in this page (1-100). | | `metric` | string ("volume" | "fee" | "fees" | "revenue" | "tvl" | "users") | No | Protocol metric to return; `fee` is an alias for `fees`. | | `offset` | integer | No | Number of metric points to skip on the first page. | | `project_id` | string | No | Surf project UUID. Prefer this exact identifier when available; it takes priority over project_name. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `project_name` | string | No | Fuzzy DeFi protocol name used only when project_id is unavailable. Ambiguous names may match an unexpected project. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### DeFi Protocol Ranking **Slug:** `SURF_LIST_PROJECT_DEFI_RANKING` Return one page of DeFi protocols ranked by TVL, fees, revenue, volume, or users. For individual pool or vault yields, use the on-chain yield ranking action instead. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Ranked protocols to return in this page (1-100). | | `metric` | string ("tvl" | "revenue" | "fees" | "volume" | "users") | Yes | Metric used to rank DeFi protocols. | | `offset` | integer | No | Number of ranked protocols to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Signal Projects **Slug:** `SURF_LIST_SIGNAL_PROJECTS` Return one page of ranked project signal cards for a 24-hour or 7-day window. Each card can include project identity, score, latest price, price changes, classified state, dimension scores, compact token signals, AI summaries, and supporting market metrics. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `offset` | integer | No | Number of ranked projects to skip on the first page. | | `time_range` | string ("24h" | "7d") | No | Window used to compute signal scores. Returns a ranked snapshot, not a time series. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Top Token Signals **Slug:** `SURF_LIST_SIGNAL_TOP_TOKENS` Return one page of daily or weekly top-token project signal cards with latest price, price changes, dimension scores, compact signals, and AI summaries. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Results to return in this page (1-100). | | `offset` | integer | No | Number of token signal cards to skip on the first page. | | `period` | string ("day" | "week") | Yes | Ranking period for the token signal cards. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token DEX Trade History **Slug:** `SURF_LIST_TOKEN_DEX_TRADES` Return one page of recent DEX swaps for a token contract on Ethereum, Base, BSC, Arbitrum, or Tron. Each trade includes the pair, bought and sold amounts, USD value, taker, transaction hash, and DEX. Set include=labels for taker entity data, and follow next_cursor for more trades. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron") | No | Blockchain containing the token contract. | | `limit` | integer | No | Trades to return in this page (1-100). | | `offset` | integer | No | Number of matching trades to skip on the first page. | | `address` | string | Yes | Token contract address, not a ticker symbol. Use a 0x-prefixed address for EVM chains or a base58 T-address for Tron. | | `include` | string | No | Set to `labels` to include entity information for each taker address. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Holders **Slug:** `SURF_LIST_TOKEN_HOLDERS` Return one page of top token holders for a contract address. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "optimism" | "polygon" | "avalanche" | "solana") | Yes | Blockchain containing the token contract. | | `limit` | integer | No | Token holders to return in this page (1-100). | | `offset` | integer | No | Number of ranked token holders to skip on the first page. | | `address` | string | Yes | Token contract address: 0x-prefixed hexadecimal for EVM chains or base58 for Solana. Do not pass a ticker symbol. | | `include` | string | No | Set to `labels` to include the full label record for each holder. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Top Transfer Counterparties **Slug:** `SURF_LIST_TOKEN_TRANSFER_COUNTERPARTIES` Return one page of a token's top receivers or senders over a selected window, ranked by transfer count, token amount, or USD value. Optionally attach entity labels or exclude common infrastructure categories. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron") | Yes | Chain where the token contract is deployed. | | `limit` | integer | No | Counterparties to return in this page (1-100). | | `metric` | string ("count" | "amount" | "amount_usd") | No | Ranking key: count for transfer frequency, amount for token quantity, or amount_usd for USD value. USD values lag approximately three days. | | `offset` | integer | No | Number of ranked counterparties to skip on the first page. | | `address` | string | Yes | Token contract address. Use a 0x-prefixed address for EVM chains; Tron also accepts a base58 T-address. Do not pass a ticker symbol. | | `include` | string | No | Set to `labels` to attach entity labels. | | `direction` | string ("to" | "from") | Yes | Ranking direction: to ranks receivers; from ranks senders. | | `time_range` | string ("1d" | "7d" | "30d" | "90d") | No | Look-back window, up to 90 days. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `exclude_labels` | array | No | Entity categories to exclude on a best-effort basis. Filtering may produce fewer than limit rows. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Transfer History **Slug:** `SURF_LIST_TOKEN_TRANSFERS` Return one page of recent transfers for a token contract on Ethereum, Base, Solana, Tron, BSC, or Arbitrum. Filter by date range, optionally attach sender and recipient labels, and follow next_cursor for more transfers. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | End of the date range as Unix seconds or YYYY-MM-DD; defaults to today. | | `chain` | string ("ethereum" | "base" | "solana" | "tron" | "bsc" | "arbitrum") | Yes | Blockchain containing the token contract. | | `from_` | string | No | Start of the date range as Unix seconds or YYYY-MM-DD; defaults to 7 days ago. | | `limit` | integer | No | Transfers to return in this page (1-100). | | `offset` | integer | No | Number of matching transfers to skip on the first page. | | `address` | string | Yes | Token contract address, not a ticker symbol. Use a 0x-prefixed address for EVM chains or a base58 address for Solana or Tron. | | `include` | string | No | Set to `labels` to include from_label and to_label entity information. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Wallet Transaction History **Slug:** `SURF_LIST_WALLET_HISTORY` Return one page of a wallet's on-chain transactions, classified by type and valued in the chain's native token. Use wallet transfer history instead for token identity and USD-valued ERC-20 or SPL transfers. Use before for deep pagination and deduplicate by tx_hash when paging across a shared timestamp. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "polygon" | "bsc" | "avalanche" | "arbitrum" | "optimism" | "fantom" | "base") | No | Blockchain whose wallet history to return. | | `limit` | integer | No | Transactions to return in this page (1-100). | | `order` | string | No | Result sort order; Surf currently supports only `desc`. | | `before` | integer | No | Return transactions strictly older than this Unix-seconds timestamp. Omit this when using offset. To continue, use the last item's timestamp; if transactions may share that second, use timestamp + 1 and deduplicate results by tx_hash. | | `offset` | integer | No | Transactions to skip on the first page. Omit this when using before. Only the most recent approximately 1,000 transactions are reachable by offset; use before for deeper history. | | `address` | string | Yes | Raw 0x-prefixed wallet address. ENS names are not supported. | | `include` | string | No | Set to `labels` to add from_label and to_label entity records. | | `sort_by` | string | No | Result sort field; Surf currently supports only `timestamp`. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Wallet DeFi Protocol Positions **Slug:** `SURF_LIST_WALLET_PROTOCOLS` Return one page of a wallet's DeFi protocol positions across lending, staking, liquidity pools, and farming, including token breakdowns and USD values. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | DeFi protocols to return in this page (1-100). | | `offset` | integer | No | Number of matching protocols to skip on the first page. | | `address` | string | Yes | Raw 0x-prefixed EVM wallet address. ENS names are not supported. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Wallet Transfer History **Slug:** `SURF_LIST_WALLET_TRANSFERS` Return one page of ERC-20 or SPL token transfers involving a wallet, with token identity, USD value, and incoming or outgoing flow. Use wallet transaction history instead for all transaction types and native values. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `flow` | string ("in" | "out") | No | Transfer direction relative to the wallet: in for incoming or out for outgoing. Omit to return both directions. | | `chain` | string ("ethereum" | "base" | "solana" | "tron" | "bsc" | "arbitrum") | No | Blockchain containing the wallet and transfers. | | `limit` | integer | No | Transfers to request per page (1-100). Solana returns at most 40 per call; use next_cursor to continue when has_more is true. | | `token` | string | No | Token contract or mint address to filter by. Use the zero address for native token transfers, or omit to return all tokens. | | `offset` | integer | No | Transfers to skip on the first page. For continuation, pass next_cursor instead of calculating an offset. | | `address` | string | Yes | Raw wallet address: 0x-prefixed hex for EVM chains or base58 for Solana. ENS names are not supported. | | `include` | string | No | Set to `labels` to include from_label and to_label entity information. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Preflight Blockchain SQL Query **Slug:** `SURF_PREFLIGHT_ONCHAIN_SQL` Validate and estimate a read-only ClickHouse SELECT or WITH query without executing it. Returns the server-bounded SQL, physical scan estimate, budgets, and guardrail warnings. This preflight consumes Surf credits. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sql` | string | Yes | Read-only ClickHouse SELECT or WITH query to validate and estimate without executing it. | | `max_rows` | integer | No | Maximum result rows in the final server-bounded execution plan. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Blockchain Structured Query **Slug:** `SURF_QUERY_ONCHAIN_DATA` Query an on-chain table with structured fields, filters, sorting, and row limits instead of raw SQL. Discover tables and columns first with Surf's on-chain schema action. Use qualified `agent.` sources, include a block_date filter for large tables, and avoid unindexed symbol filters. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sort` | array | No | ORDER BY clauses applied in sequence. | | `limit` | integer | No | Maximum rows to return (1-10000). | | `fields` | array | No | Columns to return. Omit to return all columns. | | `offset` | integer | No | Number of matching rows to skip. | | `source` | string | Yes | Fully qualified table name such as `agent.ethereum_yields_daily`. Use Surf's on-chain schema action to discover available tables. | | `filters` | array | No | WHERE conditions, which Surf combines with AND. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Blockchain SQL Query **Slug:** `SURF_QUERY_ONCHAIN_SQL` Synchronously run one read-only ClickHouse SELECT or WITH query against Surf's blockchain tables with a 30-second timeout. Use SURF_CREATE_ONCHAIN_SQL_JOB instead for durable asynchronous work. Never automatically retry a synchronous timeout. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `sql` | string | Yes | Read-only ClickHouse SELECT or WITH query. Qualify every table with the `agent` database and filter on block_date or block_number. Discover valid tables and columns with the on-chain schema action first. | | `max_rows` | integer | No | Maximum result rows returned (1-10,000). | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Airdrop Search **Slug:** `SURF_SEARCH_AIRDROP` Return one page of airdrop opportunities filtered by project keyword, lifecycle phase, reward type, task type, or open-task availability. Full task details can be included when needed. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Airdrop opportunities to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction for matching opportunities. | | `phase` | array | No | Lifecycle groups: active for open participation, claimable for eligibility or claiming, and completed for distributed rewards. | | `offset` | integer | No | Number of matching opportunities to skip on the first page. | | `sort_by` | string ("total_raise" | "xscore" | "last_status_update") | No | Field used to sort matching opportunities. | | `has_open` | boolean | No | Whether to return only opportunities with currently open tasks. | | `task_type` | string ("social" | "bounty-platforms" | "testnet" | "mainnet" | "role" | "form" | "liquidity" | "mint-nft" | "game" | "trading" | "staking" | "depin" | "node" | "ambassador" | "hold" | "check-wallet" | "mint-domain" | "predictions" | "deploy") | No | Return opportunities containing a task of this type. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `reward_type` | string ("airdrop" | "points" | "whitelist" | "nft" | "role" | "ambassador") | No | Reward type used to filter airdrop opportunities. | | `include_tasks` | boolean | No | Whether each opportunity should include its full task list. | | `project_query` | string | No | Project or coin name keyword to search for. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Project Event Search **Slug:** `SURF_SEARCH_EVENTS` Return one page of project events for a Surf project identified by exact UUID or fuzzy name, optionally filtered by event type. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("launch" | "upgrade" | "partnership" | "news" | "airdrop" | "listing" | "twitter") | No | Event type used to filter results. | | `limit` | integer | No | Events to return in this page (1-100). | | `offset` | integer | No | Number of matching events to skip on the first page. | | `project_id` | string | No | Surf project UUID. Provide project_id or project_name on the first page; prefer this exact identifier because it takes priority over project_name. Omit on continuation calls that provide next_cursor. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page without repeating project_id or project_name. | | `project_name` | string | No | Fuzzy project name. Provide project_id or project_name on the first page; use this only when project_id is unavailable. Omit on continuation calls that provide next_cursor. Ambiguous names may match an unexpected project. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fund Search **Slug:** `SURF_SEARCH_FUND` Return one page of crypto investment funds matching a name keyword, including fund identity, tier, type, logo, and top invested projects. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Funds to return in this page (1-100). | | `offset` | integer | No | Number of matching funds to skip on the first page. | | `fund_name` | string | Yes | Fund name keyword, such as a16z, Paradigm, or Coinbase Ventures. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Fundraising Event Search **Slug:** `SURF_SEARCH_FUNDRAISING` Return one page of source-backed fundraising and token-sale events, or the latest fundraising timeline when no query is provided. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `to` | string | No | Inclusive event-time upper bound as Unix seconds, YYYY-MM-DD, or RFC3339. A date-only value ends at 23:59:59 UTC; defaults to now. | | `lang` | string ("en" | "zh" | "ja" | "kr" | "ko") | No | Display and search language. Missing translations fall back to English; ko is accepted as an alias for kr. | | `from_` | string | No | Inclusive event-time lower bound as Unix seconds, YYYY-MM-DD, or RFC3339. A date-only value starts at 00:00:00 UTC. | | `limit` | integer | No | Fundraising events to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Sort direction. Relevance sorting supports descending order only. | | `query` | string | No | Project name, alias, symbol, title, or summary query. Omit it to return the latest fundraising timeline. Required when sort_by is relevance. | | `offset` | integer | No | Number of matching events to skip; offset plus limit cannot exceed 10000. | | `source` | string ("social" | "news") | No | Public source type used to filter fundraising events. | | `sort_by` | string ("recency" | "relevance" | "importance") | No | Sort results by recency, query relevance, or importance. Selecting relevance requires query. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `min_importance` | integer | No | Minimum importance score from 1 to 5; omit to include unscored events. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### News Article Search **Slug:** `SURF_SEARCH_NEWS` Return one page of crypto news articles matching a keyword or phrase, ranked by relevance with matching fragments highlighted when available. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | News articles to return in this page (1-100). | | `query` | string | Yes | Keyword or phrase to search for in crypto news articles. | | `offset` | integer | No | Number of matching articles to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Search Prediction Markets **Slug:** `SURF_SEARCH_PREDICTION_MARKET` Return one page of Polymarket and Kalshi markets with identifiers, status, volume, open interest, trade counts, current probability, and smart-money signals. Filter by platform, category, status, keyword, or exact platform identifier. Data refreshes approximately every five minutes. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Markets to return in this page (1-100). | | `order` | string ("asc" | "desc") | No | Ascending or descending sort order. | | `query` | string | No | Keyword to match against question text or ticker. Machine slugs are not searched. | | `offset` | integer | No | Number of matching markets to skip on the first page. | | `status` | string ("active" | "closed" | "finalized") | No | Market status to include. | | `sort_by` | string ("volume_1d" | "volume_7d" | "volume_30d" | "open_interest" | "trade_count_7d" | "days_to_resolution") | No | Market metric used to sort results. | | `category` | string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports") | No | Surf-curated market category to include. | | `platform` | string ("polymarket" | "kalshi") | No | Prediction-market platform to include. Omit to search both platforms. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `smart_money` | string ("bullish" | "bearish") | No | Smart-money direction to include. This filter applies only to Polymarket. | | `condition_id` | string | No | Polymarket condition ID for an exact single-market lookup. | | `market_ticker` | string | No | Kalshi market ticker for an exact single-market lookup. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Project Search **Slug:** `SURF_SEARCH_PROJECT` Return one page of crypto projects matching a project name or token ticker. Results include Surf project UUIDs for exact follow-up lookups. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Projects to return in this page (1-100). | | `query` | string | Yes | Project name or token ticker to search for. | | `offset` | integer | No | Number of matching projects to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Token Symbol Resolution **Slug:** `SURF_SEARCH_TOKEN` Resolve an exact token ticker symbol to one page of likely contract-address candidates on supported chains. Use the returned chain and address before calling token endpoints that require a contract address. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `chain` | string ("ethereum" | "base" | "bsc" | "arbitrum" | "solana" | "polygon" | "optimism" | "avalanche" | "fantom" | "tron" | "linea" | "mantle" | "blast" | "gnosis" | "zksync" | "scroll") | No | Supported chain to search. Omit to search every supported chain. | | `limit` | integer | No | Token candidates to return in this page (1-100). | | `offset` | integer | No | Number of matching token candidates to skip on the first page. | | `symbol` | string | Yes | Exact token ticker symbol to resolve, case-insensitively. Use a symbol such as USDC or PEPE, not a contract address, trading pair, or fuzzy name. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Wallet Search **Slug:** `SURF_SEARCH_WALLET` Return one page of wallet entities matching an ENS name, address label, or wallet-address prefix, including associated labels and known addresses. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Wallet entities to return in this page (1-100). | | `offset` | integer | No | Number of matching wallet entities to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `wallet_query` | string | Yes | ENS name, address label, or wallet-address prefix to search for. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not | ### Web Search **Slug:** `SURF_SEARCH_WEB` Return one page of web pages matching a keyword or phrase, optionally restricted to specific domains and including full page content. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | integer | No | Web results to return in this page (1-100). | | `query` | string | Yes | Keywords or phrase to search for on the web. | | `sites` | array | No | Domains to search, such as coindesk.com or cointelegraph.com. | | `offset` | integer | No | Number of matching web results to skip on the first page. | | `next_cursor` | string | No | Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page. | | `include_content` | boolean | No | Whether to include full page content in each result. Leave false for faster title, URL, and description discovery; set true only when the page content is needed inline. | #### Output | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `data` | string | Yes | Data from the action execution | | `error` | string | No | Error if any occurred during the execution of the action | | `successful` | boolean | Yes | Whether or not the action execution was successful or not |