Skip to main content
Surf logo
  • Category: artificial intelligence
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 122
  • Triggers: 0
  • Slug: SURF
  • Version: 20261101_00
  • Instant: Supported on the latest version. Support varies by tool.

Tools

Slug: SURF_CANCEL_ONCHAIN_SQL_JOBDurably 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

string
required
Asynchronous SQL job identifier to cancel.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_CREATE_ONCHAIN_SQL_JOBSubmit 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

string
required
Exact read-only ClickHouse SQL to execute asynchronously. The submitted SQL and date range are preserved.
integer
Maximum number of result rows to retain.
string
Stable client-generated key. Reusing it returns the retained existing job instead of starting another query.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_DEX_TOKEN_PRICEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
End of a custom range as Unix seconds or YYYY-MM-DD. Must be used with from_; together they override time_range.
string ("ethereum" | "base" | "bsc" | "arbitrum" | "optimism" | "polygon" | "avalanche" | "solana")
required
Chain the token lives on. Can be ethereum, base, bsc, arbitrum, optimism, polygon, avalanche, or solana.
string
Start of a custom range as Unix seconds or YYYY-MM-DD. Must be used with to; together they override time_range.
string
required
Token contract address: 0x-prefixed 42-character hex for EVM chains or base58 for Solana. Do not pass a ticker symbol.
string ("1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "12h" | "1d" | "7d")
Candle bucket size. Sub-day intervals from 1m through 4h are typically best for active DEX analysis.
string ("1h" | "6h" | "12h" | "24h" | "7d" | "30d" | "90d" | "180d" | "365d" | "max")
Historical window. max returns at most 1500 bars for the selected interval. Ignored when both from_ and to are set.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_BALANCE_SHEETReturn standardized balance-sheet periods for a US-listed equity. Each metric includes an availability status, and unavailable values are null.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 6 credits ($0.036) per request

Input Parameters

integer
Maximum number of financial periods to return (1-100).
string ("quarterly" | "annual")
Financial period to return.
string
required
US equity ticker symbol.
string
Inclusive latest period end date in YYYY-MM-DD format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_CANDLESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
required
US equity ticker symbol.
string
Inclusive end date in YYYY-MM-DD format; defaults to the current date in US Eastern time.
string ("day" | "week" | "month" | "year")
Candle interval.
string
Inclusive start date in YYYY-MM-DD format; defaults to one year before end_date.
integer
Number of intervals represented by each candle.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_CASH_FLOWReturn standardized cash-flow periods for a US-listed equity, with serving-layer values, status, origin, and period metadata.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 6 credits ($0.036) per request

Input Parameters

integer
Maximum number of financial periods to return (1-100).
string ("quarterly" | "ytd" | "annual" | "ttm")
Financial period to return.
string
required
US equity ticker symbol.
string
Inclusive latest period end date in YYYY-MM-DD format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_COMPANY_PROFILEReturn a standardized stock company profile or ETF product profile, including its business description and source-update metadata.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
required
US equity ticker symbol.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_FINANCIAL_METRICSReturn standardized financial ratios, growth measures, per-share values, and valuation metrics for a US-listed equity.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Maximum number of financial periods to return (1-100).
string ("quarterly" | "annual" | "ttm")
Financial metric period.
string
required
US equity ticker symbol.
string
Inclusive latest period end date in YYYY-MM-DD format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_INCOME_STATEMENTReturn standardized income-statement periods for a US-listed equity. The API passes through available periods and does not synthesize missing periods or financial values.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 6 credits ($0.036) per request

Input Parameters

integer
Maximum number of financial periods to return (1-100).
string ("quarterly" | "ytd" | "annual" | "ttm")
Financial period to return.
string
required
US equity ticker symbol.
string
Inclusive latest period end date in YYYY-MM-DD format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_LATEST_FILINGSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Maximum number of filings to return (1-20).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_LATEST_FINANCIALSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Maximum number of companies to return (1-20).
number
Minimum current-serving market capitalization in USD. Omit to disable this filter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_METAReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

array
required
US stock or ETF ticker symbols to look up, with at most 20 symbols.
boolean
Include issuer-minted crypto tokens that track each equity, with their chains and contract addresses. Omit unless tokenized counterparts are needed.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EQUITY_OVERVIEWReturn a financial overview for a US-listed equity for a selected period and date, with a limit on the number of financial periods. Values are served as reported or derived; missing values remain explicit nulls.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Maximum number of financial periods to return (1-100).
string ("quarterly" | "ytd" | "annual" | "ttm")
Financial period.
string
required
US equity ticker symbol.
string
Inclusive latest period end date in YYYY-MM-DD format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_DEPTHReturn bid and ask order-book levels for an exchange market, including spread, spread percentage, mid-price, and total bid and ask depth.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Trading pair in BASE/QUOTE form.
string ("spot" | "swap" | "perpetual" | "perp")
Market type. Use spot for spot trading or swap, perpetual, or perp for perpetual contracts.
integer
Number of bid and ask price levels to return (1-100).
string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "mexc" | "upbit" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid")
Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_FUNDING_HISTORYReturn historical funding rate records for a perpetual contract.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Trading pair for the perpetual contract.
string
Start of the time range as Unix seconds, YYYY-MM-DD, or ISO 8601. Some exchanges return only recent data regardless of this value.
integer
Maximum records to return (1-500). For a later window, pass the last returned timestamp as from_.
string ("binance" | "okx" | "bybit" | "bitget" | "gate" | "htx" | "mexc" | "bitfinex" | "bitmex" | "hyperliquid")
Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_KLINESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Trading pair in BASE/QUOTE form.
string ("spot" | "swap" | "perpetual" | "perp")
Market type. Use spot for spot trading or swap, perpetual, or perp for perpetual contracts.
string
Start of the time range as Unix seconds, YYYY-MM-DD, or an ISO 8601 date-time.
integer
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.
string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "htx" | "kucoin" | "mexc" | "upbit" | "bitfinex" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid")
Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC.
string ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M")
Candle bucket duration. This endpoint does not accept time_range; use from_ and limit to control the window.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_LONG_SHORT_RATIOReturn historical long/short ratios for a perpetual contract.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Perpetual contract pair in BASE/QUOTE form.
string
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.
integer
Maximum number of ratio points to return (1-500).
string ("binance" | "okx" | "bybit" | "bitget")
Exchange identifier.
string ("1h" | "4h" | "1d")
Bucket size for each ratio point. This endpoint does not accept time_range; use from_ and limit to control the window.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_MARKETSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
Base currency filter.
string ("spot" | "swap" | "future" | "option" | "perpetual" | "perp")
Market type filter. perpetual and perp are aliases for swap markets.
integer
Maximum number of markets to return (1-5000).
string
Quote currency filter.
Fuzzy search over the pair, base currency, and quote currency.
string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "htx" | "kucoin" | "mexc" | "upbit" | "bitfinex" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid")
Exchange identifier. Defaults to Binance; select another venue to list only that exchange’s markets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_PERPReturn a perpetual futures snapshot for a trading pair, including current funding, open interest, mark price, and index price data.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Trading pair in BASE/QUOTE form. Surf adds the perpetual settle suffix from the quote currency automatically.
array
Data groups to include: funding for current funding data and oi for open interest. Each group may be selected at most once.
string ("binance" | "okx" | "bybit" | "bitget" | "htx" | "bitfinex" | "bitmex" | "hyperliquid")
Exchange identifier. Hyperliquid uses USDC-settled perpetuals, such as BTC/USDC:USDC.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_EXCHANGE_PRICEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Trading pair in BASE/QUOTE form.
string ("spot" | "swap" | "perpetual" | "perp")
Market type. Use spot for spot trading or swap, perpetual, or perp for perpetual contracts.
string ("binance" | "okx" | "bybit" | "bitget" | "coinbase" | "kraken" | "gate" | "htx" | "kucoin" | "mexc" | "upbit" | "bitfinex" | "bitstamp" | "deribit" | "bitmex" | "bithumb" | "hyperliquid")
Exchange identifier. Hyperliquid uses USDC-settled perpetual pairs, such as BTC/USDC:USDC.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_FUND_DETAILReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
Surf fund UUID. Provide fund_id or fund_name. Prefer this exact identifier when available; it takes priority over fund_name.
string
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_ACCOUNTReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 3 credits ($0.018) per request

Input Parameters

string
required
Wallet address as a 0x EVM address or ENS name, such as vitalik.eth. Solana addresses are not supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_CANDLESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
required
Window end as Unix seconds, an ISO 8601 date-time, or a UTC date. A date means the end of that day.
string
required
Window start as Unix seconds, an ISO 8601 date-time, or a UTC date.
string
required
Hyperliquid market ID, such as BTC, kPEPE, xyz:GOLD, the canonical PURR/USDC spot pair, or an @index spot market.
string ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "8h" | "12h" | "1d" | "3d" | "1w" | "1M")
Candle granularity.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_ORDERSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
required
Wallet address: a 0x EVM address or an ENS name. Solana addresses are not supported.
integer
Maximum open orders to return. open_total reports the count before this limit is applied.
integer
Maximum terminal orders to return, newest first. historical_total reports the count before this limit is applied.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_PERFORMANCEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 3 credits ($0.018) per request

Input Parameters

string
required
Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_POSITIONSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string ("main_dex" | "xyz" | "flx" | "vntl" | "hyna" | "km" | "abcd" | "cash" | "para" | "mkts")
Market scope. Omit or use main_dex for Hyperliquid’s native market; otherwise select a builder market.
string
required
Wallet address as a 0x EVM address or ENS name, such as vitalik.eth. Solana addresses are not supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_TRADE_CONTEXTReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
required
Hyperliquid perpetual market ID, including the builder prefix for a HIP-3 market.
string
required
Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported.
string ("long" | "short")
required
Opening direction of the closed trade episode.
integer
required
Episode open time as Unix seconds, copied from the matching trade returned by the Hyperliquid trades action.
integer
required
Episode close time as Unix seconds, copied from the matching trade returned by the Hyperliquid trades action.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_HYPERLIQUID_TRADES_AGGREGATEAggregate 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
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.
string ("main_dex" | "xyz" | "flx" | "vntl" | "hyna" | "km" | "abcd" | "cash" | "para" | "mkts")
Market scope. Use main_dex for the native market or a builder-market name; omit to aggregate across all markets.
string
Inclusive close-time window start as Unix seconds, an ISO 8601 date-time, or a UTC date. Omit for full history.
string
required
Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported.
string ("day" | "symbol" | "direction" | "size_bucket" | "hold_bucket")
Rollup dimension: UTC day, market symbol, long/short direction, notional-size bucket, or holding-time bucket.
boolean
For a daily aggregation, emit zero rows for no-trade UTC days. Requires from_ to bound the dense calendar.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_KALSHI_OPEN_INTERESTReturn daily open-interest history for one Kalshi market over a selected time window. Data refreshes approximately every 30 minutes.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Kalshi market ticker. Discover valid tickers with the Kalshi markets or prediction-market search actions.
string ("7d" | "30d" | "90d" | "180d" | "1y")
History window. This endpoint returns daily points and does not accept an interval parameter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_KALSHI_PRICESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
required
Kalshi market ticker. Discover valid tickers with the Kalshi markets or prediction-market search actions.
string ("1h" | "1d" | "latest")
Point granularity: 1h for hourly OHLC, 1d for daily OHLC, or latest for the most recent trade price.
string ("7d" | "30d" | "90d" | "180d" | "1y")
History window. Ignored when interval is latest; distinct from the interval bucket size.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_KALSHI_VOLUMESReturn daily notional trading-volume history for one Kalshi market over a selected time window. Surf refreshes this data about every 30 minutes.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Kalshi market ticker. Discover valid tickers with the Kalshi markets or prediction-market search actions.
string ("7d" | "30d" | "90d" | "180d" | "1y")
History window: 7d, 30d, 90d, 180d, or 1y. This endpoint returns daily points and does not accept an interval parameter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_ETFReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date.
string
Start of the time range as Unix seconds or a YYYY-MM-DD date.
string ("asc" | "desc")
Sort direction for the returned daily flow rows.
string ("BTC" | "ETH" | "XRP" | "SOL" | "HYPE")
required
Underlying token symbol for the spot ETF flow history.
string ("flow_usd" | "timestamp")
Field used to sort the returned daily flow rows.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_FEAR_GREEDReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date.
string
Start of the time range as Unix seconds or a YYYY-MM-DD date.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_FUTURESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("asc" | "desc")
Sort direction for the ranked futures snapshot.
string ("open_interest" | "funding_rate" | "volume_24h" | "long_short_ratio")
Futures metric used to rank the returned tokens.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_LIQUIDATION_CHARTReturn time-bucketed aggregate long- and short-side liquidation volumes for a token on a specific exchange and interval.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date.
string
Start of the time range as Unix seconds or a YYYY-MM-DD date.
integer
Maximum chart points to return (1-4500).
string
required
Token ticker symbol.
string ("Binance" | "OKX" | "Bybit" | "Bitget" | "Hyperliquid" | "Gate" | "HTX" | "Bitmex" | "Bitfinex" | "CoinEx" | "Aster" | "Lighter")
Exchange whose liquidation data should be aggregated.
string ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "4h" | "6h" | "8h" | "12h" | "1d" | "1w")
Bucket size for each liquidation chart point. This endpoint does not accept time_range; use from_ and to to bound the series.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_LIQUIDATION_EXCHANGE_LISTReturn a single ranked snapshot of total, long-side, and short-side liquidation volumes by exchange for a token and aggregation window.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("asc" | "desc")
Sort direction for the ranked exchange snapshot.
string
Token ticker symbol whose liquidations should be aggregated.
string ("liquidation_usd" | "long_liquidation_usd" | "short_liquidation_usd")
Liquidation volume field used to rank exchanges.
string ("1h" | "4h" | "12h" | "24h")
Window to aggregate into one snapshot. This endpoint accepts time_range rather than interval and does not return a time series.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_ONCHAIN_INDICATORReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date. Defaults to today; the maximum range is 365 days.
string
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.
string ("nupl" | "sopr" | "mvrv" | "puell-multiple" | "nvm" | "nvt" | "nvt-golden-cross" | "exchange-flows/inflow" | "exchange-flows/outflow" | "exchange-flows/netflow" | "exchange-flows/reserve")
required
On-chain metric to return. Exchange-flow metrics include the flow direction after exchange-flows/.
string ("BTC" | "ETH")
required
Token ticker symbol whose on-chain indicator history to return.
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")
Curated exchange filter for exchange-flow metrics. Use the exchange-flow exchange-list action to discover labels.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_OPTIONSReturn options market data for one supported token, including open interest, 24-hour volume, put/call ratio, and max pain price by exchange.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("asc" | "desc")
Sort direction for the exchange rows.
string ("BTC" | "ETH" | "SOL" | "XRP" | "BNB" | "DOGE" | "ADA" | "AVAX")
required
Underlying token symbol whose options market data should be returned.
string ("open_interest" | "volume_24h")
Options metric used to sort the exchange rows.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_PRICEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of a custom range as Unix seconds or YYYY-MM-DD. Must be used with from_; together they override time_range.
string
Start of a custom range as Unix seconds or YYYY-MM-DD. Must be used with to; together they override time_range.
string
required
Single token ticker symbol, such as BTC, ETH, or SOL. Multiple symbols are not supported.
string
Quote currency, such as usd, eur, or btc.
string ("1d" | "7d" | "14d" | "30d" | "90d" | "180d" | "365d" | "max")
Historical window. Surf chooses the point granularity automatically. Ignored when both from_ and to are set.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_PRICE_INDICATORReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date. Defaults to the current time when from_ is set.
string
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.
string
required
Trading pair such as BTC/USDT, or a bare token symbol such as BTC.
object
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.
string ("binance" | "bybit" | "coinbase" | "kraken")
Exchange from which to obtain the underlying price data.
string ("1m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "12h" | "1d" | "1w")
Candlestick interval used to calculate each indicator data point.
string ("rsi" | "macd" | "ema" | "sma" | "bbands" | "stoch" | "adx" | "atr" | "cci" | "obv" | "vwap" | "dmi" | "ichimoku" | "supertrend")
required
Technical indicator to calculate for the requested trading pair.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_PUBLIC_SALEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
Surf project UUID. At least one of project_id or project_name must be non-empty; prefer this exact identifier when available.
string
Project name or token symbol used for entity resolution. At least one of project_id or project_name must be non-empty.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_MARKET_TGEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
Surf project UUID. Provide project_id or project_name; both may be supplied.
string
Project name or token symbol. Provide project_id or project_name; both may be supplied.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_NEWS_DETAILReturn the full content and metadata of one news article by an ID obtained from Surf news feed or search results.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Article ID returned by Surf news feed or search results.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_ONCHAIN_DEX_ACTIVITYReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
End of the range as Unix seconds or a YYYY-MM-DD date. Without from_, the selected time_range ends at this bound.
string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron")
required
Chain whose DEX activity to query.
string
Start of the range as Unix seconds or a YYYY-MM-DD date. With to, the range may span at most 90 days.
string
Router or contract address measured as the transaction recipient. Provide exactly one of address or project.
string
DEX project name, such as uniswap, pancakeswap, or aerodrome. Provide exactly one of project or address.
string ("total" | "day")
Aggregation shape: total returns one aggregate and day returns a newest-first daily series.
string ("1d" | "7d" | "30d" | "90d")
Look-back window, capped at 90 days. Explicit from_ or to bounds override this window.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_ONCHAIN_GAS_PRICEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("ethereum" | "polygon" | "bsc" | "arbitrum" | "optimism" | "base" | "avalanche" | "fantom" | "linea" | "cyber")
required
EVM chain whose current gas price to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_ONCHAIN_SCHEMADiscover 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
Logical table name in the agent database. Provide it to include bounded physical partition, ordering-key, and size metadata.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_ONCHAIN_SQL_JOBReturn 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

string
required
Asynchronous SQL job identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_ONCHAIN_SQL_JOB_RESULTSReturn 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

string ("json" | "csv")
Result representation: a structured JSON envelope or downloadable CSV.
string
required
Asynchronous SQL job identifier.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_ONCHAIN_TXLook 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Transaction hash as 0x-prefixed hexadecimal.
string ("ethereum" | "polygon" | "bsc" | "arbitrum" | "optimism" | "base" | "avalanche" | "fantom" | "linea" | "cyber")
required
EVM chain on which to look up the transaction.
string
Set to labels to include entity information for the sender and recipient addresses.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_POLYMARKET_OPEN_INTERESTReturn daily open-interest history in USD for one Polymarket market over a selected time window. The series is sparse, containing rows only on days with open-interest changes; data refreshes approximately every 30 minutes.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string ("7d" | "30d" | "90d" | "180d" | "1y")
History window. This endpoint returns daily points and does not accept an interval parameter.
string
required
Polymarket market condition identifier. Discover valid condition IDs with the Polymarket events or prediction-market search actions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_POLYMARKET_PRICE_OHLCVReturn 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.Instant: Supported on the latest version.Instant pricing: $0.024 per request

Input Parameters

integer
Window end as Unix seconds. Use 0 for the current time. Surf aligns cached requests to five-minute buckets.
integer
Candle interval in minutes, such as 1, 60, or 1440.
integer
Window start as Unix seconds. Use 0 for no lower bound. Surf aligns cached requests to five-minute buckets.
string
required
Polymarket condition ID. Use prediction-market search to discover condition IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_POLYMARKET_PRICESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string ("1h" | "1d" | "latest")
Point granularity: 1h for hourly points, 1d for daily points, or latest for one most-recent snapshot.
string ("7d" | "30d" | "90d" | "180d" | "1y")
History window measured backward from now. Ignored when interval is latest; distinct from the interval bucket size.
string
required
Polymarket condition identifier. Discover condition IDs with the Polymarket markets or prediction-market search actions.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_POLYMARKET_VOLUMESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
History end as a Unix timestamp in seconds; an alternative to time_range.
string ("1h" | "1d")
Bucket size for each volume point: 1h for hourly or 1d for daily. Distinct from the history window.
string
Polymarket outcome token identifier. Provide token_id or condition_id; both may be supplied. Surf resolves it to the market condition.
integer
History start as a Unix timestamp in seconds; an alternative to time_range.
string ("7d" | "30d" | "90d" | "180d" | "1y")
History window measured backward from now: 7d, 30d, 90d, 180d, or 1y. Distinct from the interval bucket size.
string ("day" | "week" | "month" | "year" | "all")
Aggregation granularity to query daily buy/sell volume: day, week, month, year, or all. Use as an alternative to interval.
string
Polymarket market condition identifier. Provide condition_id or token_id; both may be supplied.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_POLYMARKET_VOLUME_SPLITReturn 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.Instant: Supported on the latest version.Instant pricing: $0.024 per request

Input Parameters

integer
Window end as Unix seconds. Use 0 for the current time. Surf aligns cached requests to five-minute buckets.
integer
Window start as Unix seconds. Use 0 for no lower bound. Surf aligns cached requests to five-minute buckets.
string ("hour" | "day" | "week")
Time bucket used to aggregate volume: hour, day, or week.
string
required
Polymarket condition ID. Use prediction-market search to discover condition IDs.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_PROJECT_DETAILReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
Numeric X account ID used to resolve its associated project. Provide project_id, project_name, x_id, or handle.
array
Project detail sections to include.
string
X handle without the @ prefix used to resolve its associated project. Provide project_id, project_name, x_id, or handle.
string
Surf project UUID. Provide project_id, project_name, x_id, or handle. Prefer this exact identifier when available; it takes priority over project_name.
string
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_SIGNAL_DETAILReturn one project signal card by Surf token UUID or project slug, including its score, classified state, score dimensions, market data, and summaries.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
Surf token UUID. Pass exactly one of token_id or project_slug.
string ("24h" | "7d")
Window over which Surf computes the signal score.
string
Project slug. Pass exactly one of token_id or project_slug.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_TOKEN_TRANSFER_STATSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron")
required
Chain where the token contract is deployed.
string
required
Token contract address, not a ticker symbol. Use a 0x-prefixed address for EVM chains; Tron also accepts a base58 T-address.
string
Set to series to include the newest-first daily transfer breakdown.
string ("1d" | "7d" | "30d" | "90d")
Look-back window for the transfer summary, capped at 90 days.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_TOKEN_UNLOCK_SCHEDULEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
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.
string
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.
string
Token symbol such as ARB, OP, or APT. At least one of project_id or symbol is required.
string
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_WALLET_DETAILReturn a wallet’s cross-chain portfolio with selectable balance, token, label, NFT, and approval sub-resources, plus its per-chain USD breakdown.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("ethereum" | "polygon" | "bsc" | "avalanche" | "arbitrum" | "optimism" | "fantom" | "base" | "solana")
Chain filter for tokens, NFTs, and approvals. When omitted, Surf queries all EVM chains for a 0x address or Solana for a base58 address.
array
Sub-resources to include. active_chains is always returned. approvals is opt-in and triggers additional upstream calls.
string
required
Wallet address as 0x-prefixed EVM hexadecimal or Solana base58.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_WALLET_LABELS_BATCHReturn entity names, entity types, and labels for up to 100 wallet addresses in one request.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

array
required
Wallet addresses to look up, with no more than 100 per request.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_WALLET_NET_WORTHReturn historical wallet net worth in USD at daily granularity for one EVM address. The time window cannot be customized.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
required
Raw 0x-prefixed EVM wallet address. ENS names and Solana addresses are not supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_WEB_FETCHFetch one web page and convert its content to clean markdown, optionally limiting extraction, removing elements, or waiting for dynamic content with CSS selectors.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
required
URL of the web page to fetch and convert to markdown.
integer
Maximum time in milliseconds to wait for the page fetch.
string
CSS selector for page elements to remove before conversion.
string
CSS selector that limits extraction to matching page content.
string
CSS selector to wait for before extracting the page content.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_GET_X_TWEETS_BY_IDSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 7 credits ($0.042) per request

Input Parameters

array
required
Numeric tweet IDs, from 1 to 100 values. Each ID must contain 1 to 19 digits without leading zeros.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_AIRDROP_ACTIVITIESReturn one page of airdrop activities with project, reward, status, fundraising, and social metrics.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Airdrop activities to return in this page (1-100).
integer
Number of airdrop activities to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_EQUITY_ETF_HOLDINGSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
Select the composition effective on or before this YYYY-MM-DD date; the response also includes its immediately previous snapshot.
integer
Maximum holdings to return.
integer
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.
string
required
US-listed ETF or index-fund ticker symbol.
string ("equity" | "bond")
Filter holdings by instrument type.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_EQUITY_FILINGSReturn one page of verified periodic SEC filings for a US equity, including canonical filing metadata, document URLs, statement coverage, and provenance.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Results to return in this page (1-100).
integer
Number of matching filings to skip on the first page.
string
required
US equity ticker symbol.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_EQUITY_LISTINGSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Results to return in this page (1-100).
integer
Number of matching listings to skip on the first page.
string
required
Ticker used to resolve the issuer whose current verified stock listings are returned.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_EQUITY_SEGMENTSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 6 credits ($0.036) per request

Input Parameters

string
Optional provider-reported segment label to match.
integer
Maximum number of segment facts to return in this page (1-100).
integer
Number of matching segment facts to skip on the first page.
string ("quarterly" | "annual")
Financial period represented by the segment facts.
string
required
US equity ticker symbol.
string
Inclusive latest period end in YYYY-MM-DD format.
string
Inclusive earliest period start in YYYY-MM-DD format.
string
Optional normalized financial metric code to match.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Optional provider dimension key, such as product or segment.
string ("income" | "balance_sheet" | "cash_flow")
Optional financial statement family to return.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_EXCHANGE_CANDLESReturn one page of persisted OHLCV candles for a covered Bithumb, Upbit, HashKey, bitFlyer, Coinone, or Korbit spot market. Results are ordered newest first.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a date string.
string
required
Trading pair in base/quote form.
string
Start of the time range as Unix seconds or a date string.
integer
Candles to return in this page (1-300). Weekly candles allow up to 300 rows; intraday intervals are capped at 100 by Surf.
integer
Number of matching candles to skip on the first page.
string ("bithumb" | "upbit" | "hashkey" | "bitflyer" | "coinone" | "korbit")
required
Exchange identifier.
string ("5m" | "4h" | "1w")
Candle interval.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
boolean
Whether to include carry-forward candles for no-trade intervals. Set false to return raw exchange-only candles.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_EXCHANGE_COVERAGEReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Results to return in this page (1-100).
string ("asc" | "desc")
Sort order.
string
Free-text search over pair, base currency, or quote currency.
string
Quote currency filter.
integer
Number of matching markets to skip on the first page.
string ("active" | "inactive")
Market status filter.
string ("pair" | "price" | "change_24h" | "volume_24h" | "technical_score" | "latest_candle_at" | "status")
Field used to sort matching markets.
string ("bithumb" | "upbit" | "hashkey" | "bitflyer" | "coinone" | "korbit")
Exchange identifier. Omit to return all supported exchanges.
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")
Market data coverage status filter.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_FUND_PORTFOLIOReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Results to return in this page (1-100).
string ("asc" | "desc")
Sort order.
integer
Number of matching investments to skip on the first page.
string
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.
boolean
Filter by lead investor status. Omit to include all investments.
string ("invested_at" | "recent_raise" | "total_raise")
Field used to sort matching investments.
string
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.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page without repeating fund_id or fund_name.
integer
Only include investments at or after this Unix timestamp in seconds.
integer
Only include investments before this Unix timestamp in seconds.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_FUND_RANKINGReturn one page of crypto VC funds ranked by fund tier or number of invested projects, including up to five top portfolio projects per fund.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Results to return in this page (1-100).
string ("tier" | "portfolio_count")
required
Ranking metric: tier ranks lower tiers first; portfolio_count ranks by number of invested projects.
integer
Number of ranked funds to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_HYPERLIQUID_FILLSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
Inclusive window end as Unix seconds or a date; defaults to now.
string
Window start as Unix seconds or a date. Required for an ascending complete-history walk.
integer
Fills to return in this page (1-100).
string ("asc" | "desc")
Sort direction. Descending returns the recent capped feed; ascending with from_ supports a complete-history cursor walk.
integer
Exclusive window end in Unix milliseconds for descending pagination. Pair it with to_fill_id to avoid skipping fills at the same millisecond.
string
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.
string
Exact market filter, such as xyz:GOLD. Filtering may produce an empty page that still has a continuation cursor.
string
required
Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported.
string
Fill identifier paired with to_ms for lossless descending pagination through fills sharing one millisecond.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_HYPERLIQUID_LEADERBOARDReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 3 credits ($0.018) per request

Input Parameters

string ("main_dex" | "xyz" | "flx" | "vntl" | "hyna" | "km" | "abcd" | "cash" | "para" | "mkts")
Market to rank within. Omit or use main_dex for Hyperliquid’s native market; otherwise select a builder market.
integer
Traders to return in this page (1-100).
integer
Number of ranked traders to skip on the first page.
string ("total_pnl" | "win_rate" | "volume_traded")
Metric used to rank traders in descending order.
integer
Minimum trades in the selected window. Use 0 for no trade-count filter.
string ("1d" | "7d" | "30d" | "90d" | "all")
Performance window. all includes data from 2025-08-01 onward.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
integer
Minimum distinct active days in the selected window. Use 0 to disable.
integer
Minimum human-likeness score from 0 to 100. Use 0 to disable.
integer
Minimum account age in days. Use 0 to disable this filter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_HYPERLIQUID_TRADESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 3 credits ($0.018) per request

Input Parameters

string
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.
string
First-page window start as Unix seconds, an ISO 8601 date-time, or a UTC date. Omit for full history.
integer
Closed trades to return in this page (1-100).
string
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.
string
required
Wallet address as a 0x EVM address or ENS name. Solana addresses are not supported.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_KALSHI_EVENTSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Events to return in this page (1-100).
integer
Number of matching events to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Kalshi event ticker. Omit to return the top active events by volume; use prediction-market search to discover a ticker.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_KALSHI_MARKETSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Markets to return in this page (1-100).
integer
Number of matching markets to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Kalshi market ticker. Omit to return top active markets by volume; use prediction-market search to discover tickers.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_KALSHI_ORDERBOOKSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.024 per request

Input Parameters

integer
Maximum number of orderbook snapshots to return in this page (1-200).
string
required
Kalshi market ticker whose historical orderbook snapshots to return.
integer
End time in Unix milliseconds. Omit or pass 0 to use the current time.
integer
Start time in Unix milliseconds. Omit or pass 0 to use seven days ago.
string
Base64 continuation key returned as next_cursor by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_KALSHI_TRADESReturn one page of individual trades for a Kalshi market, with taker side, outcome prices, notional volume, and timestamp; Kalshi data may lag by about six hours. Filter by side, minimum notional, or time range, and follow next_cursor for more trades.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date.
string
Start of the time range as Unix seconds or a YYYY-MM-DD date.
integer
Trades to return in this page (1-500).
string ("asc" | "desc")
Sort matching trades in ascending or descending order.
integer
Number of matching trades to skip on the first page.
string
required
Kalshi market ticker. Use the Kalshi markets or prediction-market search actions to discover valid tickers.
string ("timestamp" | "notional_volume_usd")
Field used to sort matching trades.
integer
Minimum trade notional in USD; each contract has $1 notional value.
string ("yes" | "no")
Return only trades whose taker bought the yes or no side.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_MARKET_EXCHANGE_FLOW_EXCHANGESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Results to return in this page (1-100).
integer
Number of exchange filters to skip on the first page.
string ("BTC" | "ETH")
required
Token ticker symbol whose curated exchange-flow filters to return.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_MARKET_LIQUIDATION_ORDERReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
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.
string ("long" | "short")
Liquidation side to return. Omit to return both long and short orders.
string
Inclusive range start as Unix seconds or a date string.
integer
Liquidation orders to return in this page (1-100).
string ("asc" | "desc")
Sort direction.
integer
Number of matching orders to skip on the first page.
string
Base token ticker to match, such as BTC or ETH.
string ("usd_value" | "timestamp" | "price")
Liquidation-order field used to sort the results.
string ("Binance" | "OKX" | "Bybit" | "Bitget" | "Hyperliquid" | "Gate" | "HTX" | "Bitmex" | "Bitfinex" | "CoinEx" | "Aster" | "Lighter")
Exchange on which the liquidation occurred.
string
Minimum liquidated position size in USD.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next offset page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_MARKET_LISTINGSReturn one page of historical exchange listing and delisting events, filtered by date range and optionally by token, exchange, product, or event type.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
End of the event date range. Defaults to the current time.
string ("listing" | "delisting" | "cancelled" | "advanced" | "postponed")
Listing-event type to return.
string
required
Start of the event date range as YYYY-MM-DD or an ISO 8601 timestamp.
integer
Listing events to return in this page (1-100).
integer
Number of matching listing events to skip on the first page.
string
Token ticker symbol used to filter listing events.
string ("spot" | "margin" | "perp" | "pre_market_perp" | "all")
Exchange product type to return, or all product types.
string
Exchange name used to filter listing events.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_MARKET_RANKINGReturn one page of tokens ranked by market capitalization, 24-hour price change, or 24-hour trading volume, optionally filtered by token category.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Ranked tokens to return in this page (1-100).
string ("asc" | "desc")
Sort direction: descending (highest first) or ascending (lowest first).
integer
Number of ranked tokens to skip on the first page.
string ("market_cap" | "change_24h" | "volume_24h")
Field used to rank tokens: market capitalization, 24-hour price change percentage, or 24-hour trading volume.
string ("MEME" | "AI" | "AI_AGENTS" | "L1" | "L2" | "DEFI" | "GAMING" | "STABLECOIN" | "RWA" | "DEPIN" | "SOL_ECO" | "BASE_ECO" | "LST")
Token category used to filter the ranking. Omit to include all categories.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_MATCHING_MARKET_DAILYReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Daily comparison rows to return in this page (1-10000).
integer
Number of daily comparison rows to skip on the first page.
string ("1d" | "7d" | "30d" | "90d" | "180d" | "1y" | "all")
Window of daily data to return. Buckets are fixed at one day; this endpoint does not accept an interval parameter.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
required
Kalshi market ticker for the matched pair.
string
required
Polymarket condition ID for the matched pair.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_MATCHING_MARKET_PAIRSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Matching pairs to return in this page (1-100).
string ("asc" | "desc")
Ascending or descending sort order.
integer
Number of matching pairs to skip on the first page.
string ("confidence" | "polymarket_volume" | "kalshi_volume" | "spread_pct")
Field used to sort matching pairs.
string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports")
Prediction-market category to match across platforms.
string ("exact" | "related")
Return exact or related cross-platform market matches.
boolean
Whether to return only pairs where both markets are currently active.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
integer
Minimum match confidence score from 0 through 100.
string
Kalshi market ticker whose Polymarket counterpart should be found.
string
Polymarket condition ID whose Kalshi counterpart should be found.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_NEWS_FEEDReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
Return articles published on or before this time, expressed as Unix seconds or a date string.
string
Return articles published on or after this time, expressed as Unix seconds or a date string.
integer
Articles to return in this page (1-50).
integer
Number of matching articles to skip on the first page.
string ("coindesk" | "cointelegraph" | "theblock" | "decrypt" | "dlnews" | "blockbeats" | "bitcoincom" | "coinpedia" | "ambcrypto" | "cryptodaily" | "cryptopotato" | "phemex" | "panews" | "odaily" | "tradingview" | "chaincatcher" | "techflow")
News source used to filter articles.
string ("recency" | "trending")
Article order: recency returns newest first; trending is currently a deterministic newest-first alias.
array
Project names used to filter articles.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_ONCHAIN_BRIDGE_RANKINGReturn one page of bridge protocols ranked by USD transfer volume over a selected time range, including transfer counts.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Bridge protocols to return in this page (1-100).
integer
Number of ranked bridge protocols to skip on the first page.
string ("7d" | "30d" | "90d" | "180d" | "1y" | "all")
Window over which to aggregate bridge volume. Returns one ranked snapshot, not a time series.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_ONCHAIN_YIELD_RANKINGReturn one page of individual DeFi yield pools ranked by APY or TVL, optionally filtered by protocol.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Yield pools to return in this page (1-100).
string ("asc" | "desc")
Sort direction: descending (highest first) or ascending (lowest first).
integer
Number of ranked yield pools to skip on the first page.
string
Protocol name to filter by, such as lido, aave, or uniswap.
string ("apy" | "tvl_usd")
Ranking metric. APY ranking includes only pools with at least $100,000 in TVL.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_EVENTSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Events to return in this page (1-100).
integer
Number of matching events to skip on the first page.
string
required
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.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_LEADERBOARDReturn one page of Polymarket traders ranked by realized PnL, trading volume, or trade count, including aggregate position outcomes. Data refreshes approximately every five minutes.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Traders to return in this page (1-100).
string ("asc" | "desc")
Sort direction: descending (highest first) or ascending (lowest first).
integer
Number of ranked traders to skip on the first page.
string ("pnl" | "volume" | "trade_count")
Metric used to rank traders: realized PnL, volume, or trade count.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_MARKETSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Markets to return in this page (1-100).
integer
Number of matching markets to skip on the first page.
string
required
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.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_ORDERBOOKSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.024 per request

Input Parameters

integer
Maximum number of orderbook snapshots to return in this page (1-200).
integer
End time in Unix milliseconds. Omit or pass 0 to use the current time.
string
required
Polymarket token identifier whose historical orderbook snapshots to return.
integer
Start time in Unix milliseconds. Omit or pass 0 to use seven days ago.
string
Base64 continuation key returned as next_cursor by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_POSITIONSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Positions to return in this page (1-100).
integer
Number of matching positions to skip on the first page.
string
required
Polymarket proxy wallet address whose open positions to return.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_SMART_MONEYReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
End time as Unix seconds or a date string. Applies only to the trades view.
string ("positioning" | "trades")
Result view: positioning aggregates smart-wallet direction by market; trades returns individual trades of at least $10,000 with wallet metadata.
string
Start time as Unix seconds or a date string. Applies only to the trades view.
integer
Smart-money records to return in this page (1-100).
string ("asc" | "desc")
Sort direction.
integer
Number of matching records to skip on the first page.
string ("smart_wallets_involved" | "smart_buy_volume_usd" | "smart_sell_volume_usd" | "amount_usd" | "block_time")
Field used to sort the selected view.
string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports")
Surf-curated market category to filter by.
string ("bullish" | "bearish" | "neutral")
Net smart-money direction filter. Applies only to the positioning view.
string ("whale" | "large" | "mega")
Trade-size tier filter. Applies only to the trades view.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Polymarket condition identifier to filter by. Omit to browse all markets.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_POLYMARKET_TRADESReturn one page of Polymarket trades or wallet activity, filtered by market, wallet, outcome, minimum amount, or time range. Redemption and all activity views require a wallet address; redemption includes splits, merges, and redemptions, and Surf refreshes this data approximately every five minutes.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date.
string ("trade" | "redemption" | "all")
Activity type: trade returns spot trades; redemption returns splits, merges, and redemptions; all returns every activity type. Address is required for redemption and all.
string
Start of the time range as Unix seconds or a YYYY-MM-DD date.
integer
Activity records to return in this page (1-500).
integer
Number of matching activity records to skip on the first page.
string
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.
string ("timestamp" | "notional_volume_usd")
Field used to sort matching activity.
number
Minimum trade amount in USD.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Polymarket condition identifier used to filter activity by market. Provide condition_id or address on the first page.
string ("Yes" | "No")
Return only activity for the Yes or No outcome.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_PREDICTION_MARKET_ANALYTICSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Momentum markets to return in this page (1-100).
string ("asc" | "desc")
Sort direction for the momentum-markets page.
integer
Number of markets to include in the top-markets ranking (1-50).
integer
Number of momentum markets to skip. Set this explicitly to request another page; the response does not provide a continuation offset.
string ("volume_7d" | "whale_flow_net_7d" | "price_change_7d" | "oi_change_7d")
Metric used to sort the momentum-markets page.
string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports")
Prediction-market category to analyze. Omit for totals across all categories.
string ("polymarket" | "kalshi")
Prediction-market platform to analyze. Omit to combine both platforms.
string ("7d" | "30d" | "90d" | "180d" | "1y")
Window for daily category trends. The bucket size is always one day; this endpoint does not accept an interval parameter.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_PREDICTION_MARKET_CORRELATIONSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Correlation pairs to return in this page (1-100).
integer
Number of correlation pairs to skip on the first page.
string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports")
required
Prediction-market category; correlations are within-category only.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Return only pairs involving this Polymarket condition ID.
number
Minimum absolute 30-day Pearson correlation coefficient.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_PROJECT_AI_NEWSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("en" | "zh" | "ja" | "kr")
Language for AI-generated content.
integer
News items to return in this page (1-50).
integer
Number of matching news items to skip on the first page.
string
Surf project UUID. Prefer this identifier when available; it takes priority over project_name.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Fuzzy project name to use only when project_id is unavailable; ambiguous names may match an unexpected project.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_PROJECT_DEFI_METRICSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the time range as Unix seconds or a YYYY-MM-DD date.
string ("ethereum" | "polygon" | "bsc" | "avalanche" | "arbitrum" | "optimism" | "fantom" | "base" | "solana")
Blockchain on which to filter the protocol metric.
string
Start of the time range as Unix seconds or a YYYY-MM-DD date.
integer
Results to return in this page (1-100).
string ("volume" | "fee" | "fees" | "revenue" | "tvl" | "users")
Protocol metric to return; fee is an alias for fees.
integer
Number of metric points to skip on the first page.
string
Surf project UUID. Prefer this exact identifier when available; it takes priority over project_name.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
Fuzzy DeFi protocol name used only when project_id is unavailable. Ambiguous names may match an unexpected project.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_PROJECT_DEFI_RANKINGReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Ranked protocols to return in this page (1-100).
string ("tvl" | "revenue" | "fees" | "volume" | "users")
required
Metric used to rank DeFi protocols.
integer
Number of ranked protocols to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_SIGNAL_PROJECTSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Results to return in this page (1-100).
integer
Number of ranked projects to skip on the first page.
string ("24h" | "7d")
Window used to compute signal scores. Returns a ranked snapshot, not a time series.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_SIGNAL_TOP_TOKENSReturn one page of daily or weekly top-token project signal cards with latest price, price changes, dimension scores, compact signals, and AI summaries.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Results to return in this page (1-100).
integer
Number of token signal cards to skip on the first page.
string ("day" | "week")
required
Ranking period for the token signal cards.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_TOKEN_DEX_TRADESReturn one page of recent DEX swaps for a token contract on Ethereum or Base. Trades include the pair, bought and sold amounts, USD value, taker, transaction hash, and DEX; optionally request taker labels and follow the continuation cursor.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron")
Blockchain containing the token contract.
integer
Trades to return in this page (1-100).
integer
Number of matching trades to skip on the first page.
string
required
Token contract address, not a ticker symbol. Use a 0x-prefixed address for EVM chains or a base58 T-address for Tron.
string
Set to labels to include entity information for each taker address.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_TOKEN_HOLDERSReturn one page of top token holders for a contract address.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("ethereum" | "base" | "bsc" | "arbitrum" | "optimism" | "polygon" | "avalanche" | "solana")
required
Blockchain containing the token contract.
integer
Token holders to return in this page (1-100).
integer
Number of ranked token holders to skip on the first page.
string
required
Token contract address: 0x-prefixed hexadecimal for EVM chains or base58 for Solana. Do not pass a ticker symbol.
string
Set to labels to include the full label record for each holder.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_TOKEN_TRANSFER_COUNTERPARTIESReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string ("ethereum" | "base" | "bsc" | "arbitrum" | "tron")
required
Chain where the token contract is deployed.
integer
Counterparties to return in this page (1-100).
string ("count" | "amount" | "amount_usd")
Ranking key: count for transfer frequency, amount for token quantity, or amount_usd for USD value. USD values lag approximately three days.
integer
Number of ranked counterparties to skip on the first page.
string
required
Token contract address. Use a 0x-prefixed address for EVM chains; Tron also accepts a base58 T-address. Do not pass a ticker symbol.
string
Set to labels to attach entity labels.
string ("to" | "from")
required
Ranking direction: to ranks receivers; from ranks senders.
string ("1d" | "7d" | "30d" | "90d")
Look-back window, up to 90 days.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
array
Entity categories to exclude on a best-effort basis. Filtering may produce fewer than limit rows.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_TOKEN_TRANSFERSReturn one page of recent transfers for a token contract on Ethereum, Base, Tron, BSC, or Arbitrum. Filter by date range, optionally attach sender and recipient labels, and follow the continuation cursor for more transfers.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
End of the date range as Unix seconds or YYYY-MM-DD; defaults to today.
string ("ethereum" | "base" | "solana" | "tron" | "bsc" | "arbitrum")
required
Blockchain containing the token contract.
string
Start of the date range as Unix seconds or YYYY-MM-DD; defaults to 7 days ago.
integer
Transfers to return in this page (1-100).
integer
Number of matching transfers to skip on the first page.
string
required
Token contract address, not a ticker symbol. Use a 0x-prefixed address for EVM chains or a base58 address for Solana or Tron.
string
Set to labels to include from_label and to_label entity information.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_WALLET_HISTORYReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("ethereum" | "polygon" | "bsc" | "avalanche" | "arbitrum" | "optimism" | "fantom" | "base")
Blockchain whose wallet history to return.
integer
Transactions to return in this page (1-100).
string
Result sort order; Surf currently supports only desc.
integer
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.
integer
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.
string
required
Raw 0x-prefixed wallet address. ENS names are not supported.
string
Set to labels to add from_label and to_label entity records.
string
Result sort field; Surf currently supports only timestamp.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_WALLET_PROTOCOLSReturn one page of a wallet’s DeFi protocol positions across lending, staking, liquidity pools, and farming, including token breakdowns and USD values.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
DeFi protocols to return in this page (1-100).
integer
Number of matching protocols to skip on the first page.
string
required
Raw 0x-prefixed EVM wallet address. ENS names are not supported.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_LIST_WALLET_TRANSFERSReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("in" | "out")
Transfer direction relative to the wallet: in for incoming or out for outgoing. Omit to return both directions.
string ("ethereum" | "base" | "solana" | "tron" | "bsc" | "arbitrum")
Blockchain containing the wallet and transfers.
integer
Transfers to request per page (1-100). Solana returns at most 40 per call; use next_cursor to continue when has_more is true.
string
Token contract or mint address to filter by. Use the zero address for native token transfers, or omit to return all tokens.
integer
Transfers to skip on the first page. For continuation, pass next_cursor instead of calculating an offset.
string
required
Raw wallet address: 0x-prefixed hex for EVM chains or base58 for Solana. ENS names are not supported.
string
Set to labels to include from_label and to_label entity information.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_PREFLIGHT_ONCHAIN_SQLValidate 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

string
required
Read-only ClickHouse SELECT or WITH query to validate and estimate without executing it.
integer
Maximum result rows in the final server-bounded execution plan.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_QUERY_ONCHAIN_DATAQuery 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.<table> sources, include a block_date filter for large tables, and avoid unindexed symbol filters.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 5 credits ($0.030) per request

Input Parameters

array
ORDER BY clauses applied in sequence.
integer
Maximum rows to return (1-10000).
array
Columns to return. Omit to return all columns.
integer
Number of matching rows to skip.
string
required
Fully qualified table name such as agent.ethereum_yields_daily. Use Surf’s on-chain schema action to discover available tables.
array
WHERE conditions, which Surf combines with AND.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_QUERY_ONCHAIN_SQLSynchronously 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 5 credits ($0.030) per request

Input Parameters

string
required
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.
integer
Maximum result rows returned (1-10,000).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_AIRDROPReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 2 credits ($0.012) per request

Input Parameters

integer
Airdrop opportunities to return in this page (1-100).
string ("asc" | "desc")
Sort direction for matching opportunities.
array
Lifecycle groups: active for open participation, claimable for eligibility or claiming, and completed for distributed rewards.
integer
Number of matching opportunities to skip on the first page.
string ("total_raise" | "xscore" | "last_status_update")
Field used to sort matching opportunities.
boolean
Whether to return only opportunities with currently open tasks.
string ("social" | "bounty-platforms" | "testnet" | "mainnet" | "role" | "form" | "liquidity" | "mint-nft" | "game" | "trading" | "staking" | "depin" | "node" | "ambassador" | "hold" | "check-wallet" | "mint-domain" | "predictions" | "deploy")
Return opportunities containing a task of this type.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string ("airdrop" | "points" | "whitelist" | "nft" | "role" | "ambassador")
Reward type used to filter airdrop opportunities.
boolean
Whether each opportunity should include its full task list.
string
Project or coin name keyword to search for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_EVENTSReturn one page of project events for a Surf project identified by exact UUID or fuzzy name, optionally filtered by event type.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("launch" | "upgrade" | "partnership" | "news" | "airdrop" | "listing" | "twitter")
Event type used to filter results.
integer
Events to return in this page (1-100).
integer
Number of matching events to skip on the first page.
string
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.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page without repeating project_id or project_name.
string
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_FUNDReturn one page of crypto investment funds matching a name keyword, including fund identity, tier, type, logo, and top invested projects.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Funds to return in this page (1-100).
integer
Number of matching funds to skip on the first page.
string
required
Fund name keyword, such as a16z, Paradigm, or Coinbase Ventures.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_FUNDRAISINGReturn one page of source-backed fundraising and token-sale events, or the latest fundraising timeline when no query is provided.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string
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.
string ("en" | "zh" | "ja" | "kr" | "ko")
Display and search language. Missing translations fall back to English; ko is accepted as an alias for kr.
string
Inclusive event-time lower bound as Unix seconds, YYYY-MM-DD, or RFC3339. A date-only value starts at 00:00:00 UTC.
integer
Fundraising events to return in this page (1-100).
string ("asc" | "desc")
Sort direction. Relevance sorting supports descending order only.
string
Project name, alias, symbol, title, or summary query. Omit it to return the latest fundraising timeline. Required when sort_by is relevance.
integer
Number of matching events to skip; offset plus limit cannot exceed 10000.
string ("social" | "news")
Public source type used to filter fundraising events.
string ("recency" | "relevance" | "importance")
Sort results by recency, query relevance, or importance. Selecting relevance requires query.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
integer
Minimum importance score from 1 to 5; omit to include unscored events.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_NEWSReturn one page of crypto news articles matching a keyword or phrase, ranked by relevance with matching fragments highlighted when available.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
News articles to return in this page (1-100).
string
required
Keyword or phrase to search for in crypto news articles.
integer
Number of matching articles to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_PREDICTION_MARKETReturn 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 4 credits ($0.024) per request

Input Parameters

integer
Markets to return in this page (1-100).
string ("asc" | "desc")
Ascending or descending sort order.
string
Keyword to match against question text or ticker. Machine slugs are not searched.
integer
Number of matching markets to skip on the first page.
string ("active" | "closed" | "finalized")
Market status to include.
string ("volume_1d" | "volume_7d" | "volume_30d" | "open_interest" | "trade_count_7d" | "days_to_resolution")
Market metric used to sort results.
string ("crypto" | "culture" | "economics" | "financials" | "politics" | "stem" | "sports")
Surf-curated market category to include.
string ("polymarket" | "kalshi")
Prediction-market platform to include. Omit to search both platforms.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string ("bullish" | "bearish")
Smart-money direction to include. This filter applies only to Polymarket.
string
Polymarket condition ID for an exact single-market lookup.
string
Kalshi market ticker for an exact single-market lookup.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_PROJECTReturn one page of crypto projects matching a project name or token ticker. Results include Surf project UUIDs for exact follow-up lookups.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Projects to return in this page (1-100).
string
required
Project name or token ticker to search for.
integer
Number of matching projects to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_TOKENResolve 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.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

string ("ethereum" | "base" | "bsc" | "arbitrum" | "solana" | "polygon" | "optimism" | "avalanche" | "fantom" | "tron" | "linea" | "mantle" | "blast" | "gnosis" | "zksync" | "scroll")
Supported chain to search. Omit to search every supported chain.
integer
Token candidates to return in this page (1-100).
integer
Number of matching token candidates to skip on the first page.
string
required
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.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_WALLETReturn one page of wallet entities matching an ENS name, address label, or wallet-address prefix, including associated labels and known addresses.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 1 credit ($0.006) per request

Input Parameters

integer
Wallet entities to return in this page (1-100).
integer
Number of matching wallet entities to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
string
required
ENS name, address label, or wallet-address prefix to search for.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SURF_SEARCH_WEBReturn one page of web pages matching a keyword or phrase, optionally restricted to specific domains and including full page content.Instant: Supported on the latest version.Instant pricing: $0.006 per credit used; typically 3 credits ($0.018) per request

Input Parameters

integer
Web results to return in this page (1-100).
string
required
Keywords or phrase to search for on the web.
array
Domains to search, such as coindesk.com or cointelegraph.com.
integer
Number of matching web results to skip on the first page.
string
Opaque continuation cursor returned by a previous call. Pass it back unchanged to fetch the next page.
boolean
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

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not