Surf

Surf APIs

Unified pay-per-use API at surf.cascade.fyi. No signup, no API keys - just pay per call.

10 composite REST endpoints + 9 MCP tools. Payments in USDC on Solana, Base, or Tempo (MPP).

Try it

Test any endpoint with x402-proxy:

# Twitter user profile + recent tweets ($0.005)
npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/cascade_fyi

# Search Reddit ($0.005)
npx x402-proxy -X POST -H "Content-Type: application/json" \
  -d '{"query":"x402 protocol"}' \
  https://surf.cascade.fyi/api/v1/reddit/search

# Chat with Kimi K2.5 ($0.004)
npx x402-proxy -X POST -H "Content-Type: application/json" \
  -d '{"model":"moonshotai/kimi-k2.5","messages":[{"role":"user","content":"Hello"}]}' \
  https://surf.cascade.fyi/api/v1/inference/v1/chat/completions

# Web search ($0.01)
npx x402-proxy -X POST -H "Content-Type: application/json" \
  -d '{"query":"x402 protocol"}' \
  https://surf.cascade.fyi/api/v1/web/search

# Crawl a page ($0.002)
npx x402-proxy -X POST -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' \
  https://surf.cascade.fyi/api/v1/web/crawl

First run walks you through wallet setup automatically.

MCP Server

Unified MCP server at /mcp with 9 tools. Supports tool filtering via ?tools= query param.

Add to Claude Code:

npx x402-proxy mcp add surf https://surf.cascade.fyi/mcp

Or add a filtered subset:

npx x402-proxy mcp add surf "https://surf.cascade.fyi/mcp?tools=surf_twitter_search,surf_web_crawl"

Endpoint Reference

All data endpoints support both POST (JSON body) and GET (path/query params). OpenAPI spec at https://surf.cascade.fyi/openapi.json.

GET convenience routes: /api/v1/twitter/search/:query, /api/v1/twitter/tweet/:ref, /api/v1/twitter/user/:ref, /api/v1/reddit/search/:query, /api/v1/reddit/post/:ref, /api/v1/reddit/subreddit/:name, /api/v1/reddit/user/:ref, /api/v1/web/search/:query, /api/v1/web/crawl/:url

Twitter

All $0.005/call. MCP tools use the same params and return the same data.

POST /api/v1/twitter/search | MCP: surf_twitter_search

Search tweets with 50+ advanced operators. Returns ~20 tweets per page with engagement summary.

Search operators: from:user, to:user, min_faves:N, min_retweets:N, filter:media, since_time:<unix>, until_time:<unix>, lang:en, within_time:7d

The legacy since:YYYY-MM-DD / until:YYYY-MM-DD operators now return incomplete results on X - prefer start_date/end_date params (automatically converted) or since_time/until_time operators with UNIX seconds.

POST /api/v1/twitter/tweet | MCP: surf_twitter_tweet

Fetch a tweet with full thread context (all conversation participants), parent tweet, and optionally replies/quotes.

POST /api/v1/twitter/user | MCP: surf_twitter_user

Fetch user profile with ~20 recent tweets per page.

Enriched fields: thread context (full conversation up to 20 tweets), engagement_rate, content_type (original/reply/quote/retweet/media/link_share), topic extraction (hashtags, domains, mentions), auto-crawled article content from URLs in tweets.

Reddit

All $0.005/call. MCP tools use the same params and return the same data.

POST /api/v1/reddit/search | MCP: surf_reddit_search

Search posts across Reddit with sort and time filters.

POST /api/v1/reddit/post | MCP: surf_reddit_post

Fetch a post with comments, depth/sort control.

POST /api/v1/reddit/subreddit | MCP: surf_reddit_subreddit

Fetch subreddit info and top posts.

POST /api/v1/reddit/user | MCP: surf_reddit_user

Fetch a user profile with recent posts and comments.

Enriched fields: domain, stickied, locked, edited, distinguished, awards, crosspost_parent, comment link context.

Web

POST /api/v1/web/search | MCP: surf_web_search | $0.01/call

Semantic web search powered by Exa. Returns titles, URLs, snippets, and highlights.

POST /api/v1/web/crawl | MCP: surf_web_crawl | $0.002/call

Extract content from web pages as markdown, HTML, or text. Supports PDF extraction.

Enriched fields (search): published_date, author, score, query-relevant highlights, autoprompt query rewriting.

Inference

POST /api/v1/inference/v1/chat/completions | OpenAI-compatible chat completion

Model list at GET /api/v1/inference/v1/models.

Models (21):

Flat models charge a fixed price per request. Dynamic models price based on input size, max_tokens, and model rates. The :online variants include live X/Twitter + web search via xAI native tools.

Streaming: Set stream: true for SSE. Parse data: lines, stop on data: [DONE].

const res = await fetchX402("https://surf.cascade.fyi/api/v1/inference/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "moonshotai/kimi-k2.5",
    messages: [{ role: "user", content: "Write a haiku" }],
    stream: true,
  }),
});

const reader = res.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  for (const line of chunk.split("\n")) {
    if (line.startsWith("data: ") && line !== "data: [DONE]") {
      const data = JSON.parse(line.slice(6));
      process.stdout.write(data.choices[0]?.delta?.content ?? "");
    }
  }
}

Rate limits: 20 requests per 60 seconds per wallet. Duplicate payment headers are rejected.

Integrate with @x402/fetch

npm install @x402/fetch @x402/evm @x402/svm

Solana wallet

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

const svmSigner = await createKeyPairSignerFromBytes(base58.decode(process.env.SVM_PRIVATE_KEY!));
const client = new x402Client();
registerExactSvmScheme(client, { signer: svmSigner });
const fetchX402 = wrapFetchWithPayment(fetch, client);

Base (EVM) wallet

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer });
const fetchX402 = wrapFetchWithPayment(fetch, client);

Then use like normal fetch:

const res = await fetchX402("https://surf.cascade.fyi/api/v1/twitter/user/cascade_fyi");
const { data } = await res.json();

Debugging

npx x402-proxy https://surf.cascade.fyi/api/v1/twitter/user/cascade_fyi | jq '.data'
npx x402-proxy wallet            # addresses and balances
npx x402-proxy wallet history    # payment log

Pagination

Paginated endpoints return meta.has_next_page and meta.next_cursor. Pass cursor in the next request:

let cursor: string | undefined;
const allTweets = [];

do {
  const res = await fetchX402("https://surf.cascade.fyi/api/v1/twitter/user", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ ref: "cascade_fyi", cursor }),
  });
  const { data, meta } = await res.json();
  allTweets.push(...data.tweets);
  cursor = meta?.has_next_page ? meta.next_cursor : undefined;
} while (cursor);

Tips

• Use format: "markdown" for LLM-friendly web crawl output
• Batch URLs with the urls array to crawl multiple pages in one paid request
• The inference API is OpenAI-compatible - existing code works by changing the base URL
• Use comment_limit: 0 to fetch a Reddit post without comments (faster)
• Quote URLs containing ? or & in shell commands to avoid glob expansion