@surf-ai/sdk 0.1.5-beta → 1.0.0-alpha.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -159
- package/dist/chunk-4NA3GKVD.js +100 -0
- package/dist/{client-3YMIRPDV.js → client-Z45B2GYT.js} +1 -1
- package/dist/db/index.cjs +63 -37
- package/dist/db/index.d.cts +5 -2
- package/dist/db/index.d.ts +5 -2
- package/dist/db/index.js +63 -37
- package/dist/server/index.cjs +211 -190
- package/dist/server/index.d.cts +204 -16
- package/dist/server/index.d.ts +204 -16
- package/dist/server/index.js +131 -153
- package/package.json +6 -29
- package/dist/chunk-J4OMYO3F.js +0 -70
- package/dist/react/index.d.ts +0 -3450
- package/dist/react/index.js +0 -1092
- package/src/theme/index.css +0 -314
package/dist/server/index.js
CHANGED
|
@@ -1,26 +1,35 @@
|
|
|
1
1
|
import {
|
|
2
2
|
__require,
|
|
3
3
|
get,
|
|
4
|
-
post
|
|
5
|
-
|
|
4
|
+
post,
|
|
5
|
+
readAdminApiKey
|
|
6
|
+
} from "../chunk-4NA3GKVD.js";
|
|
6
7
|
|
|
7
8
|
// src/server/runtime.ts
|
|
8
9
|
import express from "express";
|
|
9
10
|
import cors from "cors";
|
|
10
11
|
import fs from "fs";
|
|
11
12
|
import path from "path";
|
|
12
|
-
import { createProxyMiddleware, responseInterceptor } from "http-proxy-middleware";
|
|
13
13
|
import { Cron } from "croner";
|
|
14
|
+
function requireBearerAuth(req, res, next) {
|
|
15
|
+
const apiKey = readAdminApiKey();
|
|
16
|
+
if (!apiKey) {
|
|
17
|
+
return res.status(503).json({ error: "SURF_API_KEY is not configured" });
|
|
18
|
+
}
|
|
19
|
+
if (req.headers.authorization !== `Bearer ${apiKey}`) {
|
|
20
|
+
return res.status(401).json({ error: "Unauthorized" });
|
|
21
|
+
}
|
|
22
|
+
next();
|
|
23
|
+
}
|
|
14
24
|
function createServer(options = {}) {
|
|
15
|
-
const port = options.port
|
|
25
|
+
const port = options.port ?? (process.env.PORT ? Number.parseInt(process.env.PORT, 10) : void 0);
|
|
26
|
+
if (!Number.isInteger(port)) {
|
|
27
|
+
throw new Error("createServer requires a port via options.port or process.env.PORT");
|
|
28
|
+
}
|
|
16
29
|
const routesDir = options.routesDir || path.join(process.cwd(), "routes");
|
|
17
30
|
const cronDir = options.cronDir || process.cwd();
|
|
18
|
-
const enableProxy = options.proxy !== false;
|
|
19
31
|
const app = express();
|
|
20
32
|
app.use(cors());
|
|
21
|
-
if (enableProxy) {
|
|
22
|
-
setupProxy(app, port);
|
|
23
|
-
}
|
|
24
33
|
app.use(express.json());
|
|
25
34
|
app.get("/api/health", (_req, res) => {
|
|
26
35
|
res.json({ status: "ok" });
|
|
@@ -30,12 +39,13 @@ function createServer(options = {}) {
|
|
|
30
39
|
if (!file.endsWith(".js") && !file.endsWith(".ts")) continue;
|
|
31
40
|
const name = file.replace(/\.(js|ts)$/, "");
|
|
32
41
|
try {
|
|
33
|
-
const
|
|
34
|
-
const handler = route.default || route;
|
|
42
|
+
const handler = __require(path.join(routesDir, file));
|
|
35
43
|
if (typeof handler === "function") {
|
|
36
44
|
app.use(`/api/${name}`, handler);
|
|
37
45
|
console.log(`Route registered: /api/${name}`);
|
|
46
|
+
continue;
|
|
38
47
|
}
|
|
48
|
+
throw new Error(`Route module must export a handler function via module.exports`);
|
|
39
49
|
} catch (err) {
|
|
40
50
|
console.error(`Failed to load route ${file}: ${err.message}`);
|
|
41
51
|
}
|
|
@@ -59,55 +69,6 @@ function createServer(options = {}) {
|
|
|
59
69
|
}
|
|
60
70
|
};
|
|
61
71
|
}
|
|
62
|
-
function env(surfName, legacyName) {
|
|
63
|
-
return process.env[surfName] || process.env[legacyName];
|
|
64
|
-
}
|
|
65
|
-
function setupProxy(app, port) {
|
|
66
|
-
const gatewayUrl = env("SURF_DEPLOYED_GATEWAY_URL", "GATEWAY_URL");
|
|
67
|
-
const appToken = env("SURF_DEPLOYED_APP_TOKEN", "APP_TOKEN");
|
|
68
|
-
const proxyBase = env("SURF_SANDBOX_PROXY_BASE", "DATA_PROXY_BASE");
|
|
69
|
-
const isDeployed = Boolean(gatewayUrl && appToken);
|
|
70
|
-
const bufferResponse = responseInterceptor(async (buf) => buf);
|
|
71
|
-
if (isDeployed) {
|
|
72
|
-
app.use("/proxy", createProxyMiddleware({
|
|
73
|
-
target: gatewayUrl,
|
|
74
|
-
changeOrigin: true,
|
|
75
|
-
selfHandleResponse: true,
|
|
76
|
-
pathRewrite: (p) => "/gateway/v1" + p,
|
|
77
|
-
headers: {
|
|
78
|
-
Authorization: `Bearer ${appToken}`,
|
|
79
|
-
"Accept-Encoding": "identity"
|
|
80
|
-
},
|
|
81
|
-
on: { proxyRes: bufferResponse }
|
|
82
|
-
}));
|
|
83
|
-
const loopback = `http://127.0.0.1:${port}/proxy`;
|
|
84
|
-
process.env.SURF_SANDBOX_PROXY_BASE = loopback;
|
|
85
|
-
process.env.DATA_PROXY_BASE = loopback;
|
|
86
|
-
} else if (proxyBase) {
|
|
87
|
-
const target = proxyBase.replace(/\/proxy$/, "");
|
|
88
|
-
app.use(createProxyMiddleware({
|
|
89
|
-
target,
|
|
90
|
-
changeOrigin: true,
|
|
91
|
-
selfHandleResponse: true,
|
|
92
|
-
pathFilter: "/proxy",
|
|
93
|
-
on: {
|
|
94
|
-
proxyReq: (proxyReq, req) => {
|
|
95
|
-
console.log(`[proxy] >> ${req.method} ${req.originalUrl}`);
|
|
96
|
-
},
|
|
97
|
-
proxyRes: responseInterceptor(async (buf, proxyRes, req) => {
|
|
98
|
-
const status = proxyRes.statusCode;
|
|
99
|
-
const tag = status && status >= 400 ? "ERR" : "OK";
|
|
100
|
-
console.log(`[proxy] << ${status} ${tag} ${req.method} ${req.originalUrl} bytes=${buf.length}`);
|
|
101
|
-
return buf;
|
|
102
|
-
}),
|
|
103
|
-
error: (err, req, res) => {
|
|
104
|
-
console.error(`[proxy] !! ${req.method} ${req.originalUrl} error: ${err.message}`);
|
|
105
|
-
if (!res.headersSent) res.status(502).json({ error: err.message });
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
}));
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
72
|
var schemaSync = { run: async () => {
|
|
112
73
|
}, watch: () => {
|
|
113
74
|
} };
|
|
@@ -147,7 +108,7 @@ function setupSchemaSync(app, schemaDir) {
|
|
|
147
108
|
(t) => t && typeof t === "object" && /* @__PURE__ */ Symbol.for("drizzle:Name") in t
|
|
148
109
|
);
|
|
149
110
|
if (tables.length === 0) return;
|
|
150
|
-
const { get: dbGet, post: dbPost } = await import("../client-
|
|
111
|
+
const { get: dbGet, post: dbPost } = await import("../client-Z45B2GYT.js");
|
|
151
112
|
await dbPost("db/provision");
|
|
152
113
|
const existing = (await dbGet("db/tables")).map((t) => t.name);
|
|
153
114
|
const missing = tables.filter((t) => !existing.includes(getTableConfig(t).name));
|
|
@@ -211,7 +172,7 @@ function setupSchemaSync(app, schemaDir) {
|
|
|
211
172
|
}
|
|
212
173
|
console.error("DB schema sync failed after all retries");
|
|
213
174
|
}
|
|
214
|
-
app.post("/api/__sync-schema", async (_req, res) => {
|
|
175
|
+
app.post("/api/__sync-schema", requireBearerAuth, async (_req, res) => {
|
|
215
176
|
try {
|
|
216
177
|
await syncWithRetry(2, 1500);
|
|
217
178
|
res.json({ ok: true });
|
|
@@ -315,16 +276,7 @@ function setupCron(app, cronDir) {
|
|
|
315
276
|
console.log(`Cron registered: [${task.id}] ${task.name} (${task.schedule})`);
|
|
316
277
|
}
|
|
317
278
|
}
|
|
318
|
-
|
|
319
|
-
app.use("/api/cron", (req, res, next) => {
|
|
320
|
-
const appToken = envFn("SURF_DEPLOYED_APP_TOKEN", "APP_TOKEN");
|
|
321
|
-
if (!appToken) return next();
|
|
322
|
-
const auth = req.headers.authorization;
|
|
323
|
-
if (!auth || auth !== `Bearer ${appToken}`) {
|
|
324
|
-
return res.status(401).json({ error: "Unauthorized" });
|
|
325
|
-
}
|
|
326
|
-
next();
|
|
327
|
-
});
|
|
279
|
+
app.use("/api/cron", requireBearerAuth);
|
|
328
280
|
app.get("/api/cron", (_req, res) => {
|
|
329
281
|
res.json(cronTasks.map((t) => {
|
|
330
282
|
const state = cronState.get(t.id) || { lastRunAt: null, lastStatus: null, lastError: null };
|
|
@@ -430,223 +382,247 @@ function setupCron(app, cronDir) {
|
|
|
430
382
|
|
|
431
383
|
// src/data/categories/exchange.ts
|
|
432
384
|
var exchange = {
|
|
433
|
-
/**
|
|
385
|
+
/** Returns order book bid/ask levels with computed stats. **Included fields:** spread, spread percentage, mid-price, and total bid/ask depth. Use `limit` to control the number of price levels (1–100, default 20). Set `type=swap` to query perpetual contract order books instead of spot. */
|
|
434
386
|
depth: (params) => get("exchange/depth", params),
|
|
435
|
-
/**
|
|
387
|
+
/** Returns historical funding rate records for a perpetual contract. **Pagination:** use `from` to set the start time and `limit` to control result count. For longer history, pass the last returned timestamp as the next `from` value. **Note:** not all exchanges support historical queries via `from`; some only return recent data regardless. For the latest funding rate snapshot, see `/exchange/perp?fields=funding`. */
|
|
436
388
|
funding_history: (params) => get("exchange/funding-history", params),
|
|
437
|
-
/**
|
|
389
|
+
/** Returns OHLCV candlestick data with period summary stats (high, low, total volume). **Intervals:** 15 options from `1m` to `1M`. **Pagination:** use `from` to set the start time and `limit` to control candle count. For longer ranges, pass the last returned candle's timestamp as the next `from` value. Exchange-side limits vary (200–1000 per request). Set `type=swap` to query perpetual contract candles instead of spot. */
|
|
438
390
|
klines: (params) => get("exchange/klines", params),
|
|
439
|
-
/**
|
|
391
|
+
/** Returns historical long/short ratio for a perpetual contract. **Included fields:** ratio value, long account percentage, short account percentage. **Granularity:** `interval` supports `1h`, `4h`, `1d`. **Pagination:** use `from` for start time and `limit` for result count. For longer history, pass the last returned timestamp as the next `from` value. **Note:** not all exchanges support historical queries via `from`; some only return recent data regardless. Just pass the base pair (e.g. `pair=BTC/USDT`). For aggregated cross-exchange long/short ratio, see `/market/futures`. */
|
|
440
392
|
long_short_ratio: (params) => get("exchange/long-short-ratio", params),
|
|
441
|
-
/**
|
|
393
|
+
/** Returns trading pairs available on an exchange. **Filters:** `type` (`spot`, `swap`, `future`, `option`) or free-text `search`. **Included fields:** pair name, base/quote currencies, market type, active status, and default fee rates. Use the returned `pair` values as the `pair` parameter in other exchange endpoints. */
|
|
442
394
|
markets: (params) => get("exchange/markets", params),
|
|
443
|
-
/**
|
|
395
|
+
/** Returns a combined snapshot of perpetual contract data for a pair. **Available fields** (via `fields`): - `funding` — current funding rate, next settlement, mark/index price - `oi` — open interest in contracts and USD Just pass the base pair (e.g. `pair=BTC/USDT`). The `:USDT` swap suffix is added automatically. */
|
|
444
396
|
perp: (params) => get("exchange/perp", params),
|
|
445
|
-
/**
|
|
397
|
+
/** Returns the real-time ticker for a trading pair. **Included fields:** last price, bid/ask, 24h high/low, 24h volume, 24h price change. Set `type=swap` to query perpetual contract prices instead of spot. For historical price trends, use `/market/price`. */
|
|
446
398
|
price: (params) => get("exchange/price", params)
|
|
447
399
|
};
|
|
448
400
|
|
|
449
401
|
// src/data/categories/fund.ts
|
|
450
402
|
var fund = {
|
|
451
|
-
/**
|
|
403
|
+
/** Returns a fund's **profile metadata**. **Included fields:** X accounts, team members, recent research, invested project count. This does NOT return the list of investments — use `/fund/portfolio` for that. **Lookup:** by UUID (`id`) or name (`q`). Returns 404 if not found. */
|
|
452
404
|
detail: (params) => get("fund/detail", params),
|
|
453
|
-
/**
|
|
405
|
+
/** Returns investment rounds for a fund's portfolio, sorted by date (newest first). A project may appear multiple times if the fund participated in multiple rounds. **Included fields:** project name, logo, date, raise amount, lead investor status. **Lookup:** by UUID (`id`) or name (`q`). */
|
|
454
406
|
portfolio: (params) => get("fund/portfolio", params),
|
|
455
|
-
/**
|
|
407
|
+
/** Returns top-ranked funds by a specified metric. **Available metrics:** `tier` (lower is better), `portfolio_count` (number of invested projects). */
|
|
456
408
|
ranking: (params) => get("fund/ranking", params)
|
|
457
409
|
};
|
|
458
410
|
|
|
459
411
|
// src/data/categories/kalshi.ts
|
|
460
412
|
var kalshi = {
|
|
461
|
-
/**
|
|
413
|
+
/** Returns Kalshi events with nested markets, optionally filtered by `event_ticker`. Each event includes market count and a list of markets. **Data refresh:** ~30 minutes */
|
|
462
414
|
events: (params) => get("prediction-market/kalshi/events", params),
|
|
463
|
-
/**
|
|
415
|
+
/** Returns Kalshi markets, optionally filtered by `market_ticker`. Each market includes price, volume, and status. **Data refresh:** ~30 minutes */
|
|
464
416
|
markets: (params) => get("prediction-market/kalshi/markets", params),
|
|
465
|
-
/**
|
|
417
|
+
/** Returns daily open interest history for a Kalshi market, filtered by `time_range`. **Data refresh:** ~30 minutes */
|
|
466
418
|
open_interest: (params) => get("prediction-market/kalshi/open-interest", params),
|
|
467
|
-
/**
|
|
419
|
+
/** Returns price history for a Kalshi market. **Interval options:** - `interval=1d` — daily OHLC from market reports (~30 min delay) - `interval=latest` — real-time price from trades **Data refresh:** ~30 minutes (daily), real-time (latest) */
|
|
468
420
|
prices: (params) => get("prediction-market/kalshi/prices", params),
|
|
469
|
-
/**
|
|
421
|
+
/** Returns top-ranked Kalshi markets by last day's `notional_volume_usd` or `open_interest`. **Filters:** `status`. **Data refresh:** ~30 minutes */
|
|
470
422
|
ranking: (params) => get("prediction-market/kalshi/ranking", params),
|
|
471
|
-
/**
|
|
423
|
+
/** Returns individual trade records for a Kalshi market. **Filters:** `taker_side`, `min_contracts`, and date range. **Sort:** `timestamp` or `num_contracts`. **Data refresh:** real-time */
|
|
472
424
|
trades: (params) => get("prediction-market/kalshi/trades", params),
|
|
473
|
-
/**
|
|
425
|
+
/** Returns daily trading volume history for a Kalshi market, filtered by `time_range`. **Data refresh:** ~30 minutes */
|
|
474
426
|
volumes: (params) => get("prediction-market/kalshi/volumes", params)
|
|
475
427
|
};
|
|
476
428
|
|
|
477
429
|
// src/data/categories/market.ts
|
|
478
430
|
var market = {
|
|
479
|
-
/**
|
|
431
|
+
/** Returns daily ETF flow history for US spot ETFs. **Included fields:** net flow (USD), token price, per-ticker breakdown. Sorted by date descending. `symbol`: `BTC` or `ETH`. */
|
|
480
432
|
etf: (params) => get("market/etf", params),
|
|
481
|
-
/**
|
|
433
|
+
/** Returns Bitcoin Fear & Greed Index history. **Included fields:** index value (0-100), classification label, BTC price at each data point. Sorted newest-first. Use `from`/`to` to filter by date range. */
|
|
482
434
|
fear_greed: (params) => get("market/fear-greed", params),
|
|
483
|
-
/**
|
|
435
|
+
/** Returns futures market data across all tracked tokens. **Included fields:** open interest, funding rate, long/short ratio, 24h volume. Sorted by `volume_24h` by default — use `sort_by` to change. */
|
|
484
436
|
futures: (params) => get("market/futures", params),
|
|
485
|
-
/**
|
|
437
|
+
/** Returns OHLC-style aggregated liquidation data for a token on a specific exchange. **Filters:** `symbol`, `exchange`, `interval`. Useful for charting liquidation volume over time. */
|
|
486
438
|
liquidation_chart: (params) => get("market/liquidation/chart", params),
|
|
487
|
-
/**
|
|
439
|
+
/** Returns liquidation breakdown by exchange. **Included fields:** total, long, and short volumes in USD. **Filters:** `symbol` and `time_range` (`1h`, `4h`, `12h`, `24h`). */
|
|
488
440
|
liquidation_exchange_list: (params) => get("market/liquidation/exchange-list", params),
|
|
489
|
-
/**
|
|
441
|
+
/** Returns individual large liquidation orders above a USD threshold (`min_amount`, default 10000). **Filters:** `exchange` and `symbol`. For aggregate totals and long/short breakdown by exchange, use `/market/liquidation/exchange-list`. For historical liquidation charts, use `/market/liquidation/chart`. */
|
|
490
442
|
liquidation_order: (params) => get("market/liquidation/order", params),
|
|
491
|
-
/**
|
|
443
|
+
/** Returns on-chain indicator time-series for BTC or ETH. **Available metrics:** `nupl`, `sopr`, `mvrv`, `puell-multiple`, `nvm`, `nvt`, `nvt-golden-cross`, `exchange-flows` (inflow/outflow/netflow/reserve). */
|
|
492
444
|
onchain_indicator: (params) => get("market/onchain-indicator", params),
|
|
493
|
-
/**
|
|
445
|
+
/** Returns options market data for a `symbol`. **Included fields:** open interest, volume, put/call ratio, max pain price. */
|
|
494
446
|
options: (params) => get("market/options", params),
|
|
495
|
-
/**
|
|
447
|
+
/** Returns historical price data points for a token over a specified time range. **Time range options:** - Predefined: `1d`, `7d`, `14d`, `30d`, `90d`, `180d`, `365d`, `max` - Custom: use `from` / `to` (Unix seconds or `YYYY-MM-DD`) **Granularity** is automatic based on range: - `1d` → 5-minute intervals - `7d`–`90d` → hourly - `180d`+ → daily */
|
|
496
448
|
price: (params) => get("market/price", params),
|
|
497
|
-
/**
|
|
449
|
+
/** Returns a technical indicator for a trading pair on a given exchange and interval. **Modes:** - Set `from`/`to` for time-series - Omit for latest value only **Indicator-specific tuning** via `options` (e.g. `period:7`, `fast_period:8,slow_period:21,signal_period:5`, `period:10,stddev:1.5`). **Available indicators:** `rsi`, `macd`, `ema`, `sma`, `bbands`, `stoch`, `adx`, `atr`, `cci`, `obv`, `vwap`, `dmi`, `ichimoku`, `supertrend`. */
|
|
498
450
|
price_indicator: (params) => get("market/price-indicator", params),
|
|
499
|
-
/**
|
|
451
|
+
/** Returns tokens ranked by a specified metric. **Available metrics:** `market_cap`, `top_gainers`, `top_losers`, `volume`. **Note:** `top_gainers` and `top_losers` rank by 24h price change within the top 250 coins by market cap. For circulating supply, FDV, ATH/ATL, use `/project/detail?fields=token_info`. */
|
|
500
452
|
ranking: (params) => get("market/ranking", params)
|
|
501
453
|
};
|
|
502
454
|
|
|
455
|
+
// src/data/categories/matching.ts
|
|
456
|
+
var matching = {
|
|
457
|
+
/** Returns daily volume and open interest comparison for a specific matched market pair. Both `polymarket_condition_id` and `kalshi_market_ticker` are required. **Volume units:** Polymarket = USD, Kalshi = contracts. */
|
|
458
|
+
market_daily: (params) => get("prediction-market/matching/daily", params),
|
|
459
|
+
/** Given a Polymarket condition_id or Kalshi market_ticker, find the corresponding match on the other platform. Provide at least one of `polymarket_condition_id` or `kalshi_market_ticker`. When both are provided, results are filtered to pairs matching both (useful for verifying a specific pair). */
|
|
460
|
+
market_find: (params) => get("prediction-market/matching/find", params),
|
|
461
|
+
/** Returns one-to-one matched market pairs between Polymarket and Kalshi. Each pair maps a Polymarket condition_id to a Kalshi market_ticker with a confidence score. **Volume units differ:** Polymarket = USD, Kalshi = contracts ($1 binary options). **Data refresh:** seed-driven, updated periodically. */
|
|
462
|
+
market_pairs: (params) => get("prediction-market/matching/pairs", params)
|
|
463
|
+
};
|
|
464
|
+
|
|
503
465
|
// src/data/categories/news.ts
|
|
504
466
|
var news = {
|
|
505
467
|
/** Returns the full content of a single news article by its ID (returned as `id` in feed and search results). */
|
|
506
468
|
detail: (params) => get("news/detail", params),
|
|
507
|
-
/**
|
|
469
|
+
/** Returns crypto news from major sources. **Filters:** `source` (enum), `project`, and time range (`from`/`to`). **Sort:** `recency` (default) or `trending`. Use the detail endpoint with article `id` for full content. */
|
|
508
470
|
feed: (params) => get("news/feed", params)
|
|
509
471
|
};
|
|
510
472
|
|
|
511
473
|
// src/data/categories/onchain.ts
|
|
512
474
|
var onchain = {
|
|
513
|
-
/**
|
|
475
|
+
/** Returns bridge protocols ranked by total USD volume over a specified time range. */
|
|
514
476
|
bridge_ranking: (params) => get("onchain/bridge/ranking", params),
|
|
515
|
-
/**
|
|
477
|
+
/** Returns the current gas price for an EVM chain via `eth_gasPrice` JSON-RPC. **Included fields:** gas price in both wei (raw) and Gwei (human-readable). **Supported chains:** `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`. */
|
|
516
478
|
gas_price: (params) => get("onchain/gas-price", params),
|
|
517
|
-
/**
|
|
479
|
+
/** Executes a structured JSON query on blockchain data. No raw SQL needed — specify source, fields, filters, sort, and pagination. All tables live in the **agent** database. Use `GET /v1/onchain/schema` to discover available tables and their columns. **Key rules:** - **Source format:** `agent.<table_name>` (e.g. `agent.ethereum_transactions`, `agent.ethereum_dex_trades`) - Max 10,000 rows (default 20), 30s timeout - **Always filter on block_date** — it is the partition key. Without it, queries scan billions of rows and will timeout **Data refresh:** ~24 hours. ## Example ```json { "source": "agent.ethereum_dex_trades", "fields": ["block_time", "project", "token_pair", "amount_usd", "taker"], "filters": [ {"field": "block_date", "op": "gte", "value": "2025-03-01"}, {"field": "project", "op": "eq", "value": "uniswap"}, {"field": "amount_usd", "op": "gte", "value": 100000} ], "sort": [{"field": "amount_usd", "order": "desc"}], "limit": 20 } ``` */
|
|
518
480
|
structured_query: (body) => post("onchain/query", body),
|
|
519
|
-
/**
|
|
481
|
+
/** Returns table metadata for all available on-chain databases. **Included fields:** database name, table name, column names, types, and comments. */
|
|
520
482
|
schema: () => get("onchain/schema"),
|
|
521
|
-
/**
|
|
483
|
+
/** Executes a raw SQL SELECT query against blockchain data. All tables live in the **agent** database. Use `GET /v1/onchain/schema` to discover available tables and their columns before writing queries. ## Rules - Only SELECT/WITH statements allowed (read-only) - All table references must be database-qualified: `agent.<table_name>` - Max 10,000 rows (default 1,000), 30s timeout - **Always filter on block_date or block_number** — partition key, without it queries will timeout - Avoid `SELECT *` on large tables — specify only the columns you need **Data refresh:** ~24 hours. ## Example ```sql SELECT block_time, token_pair, amount_usd, taker, tx_hash FROM agent.ethereum_dex_trades WHERE block_date >= today() - 7 AND project = 'uniswap' AND amount_usd > 100000 ORDER BY amount_usd DESC LIMIT 20 ``` */
|
|
522
484
|
sql: (body) => post("onchain/sql", body),
|
|
523
|
-
/**
|
|
485
|
+
/** Returns transaction details by hash. All numeric fields are hex-encoded — use parseInt(hex, 16) to convert. **Supported chains:** `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `base`, `avalanche`, `fantom`, `linea`, `cyber`. Returns 404 if the transaction is not found. */
|
|
524
486
|
tx: (params) => get("onchain/tx", params),
|
|
525
|
-
/**
|
|
487
|
+
/** Returns DeFi yield pools ranked by APY or TVL. Returns the latest snapshot. Filter by protocol. */
|
|
526
488
|
yield_ranking: (params) => get("onchain/yield/ranking", params)
|
|
527
489
|
};
|
|
528
490
|
|
|
529
491
|
// src/data/categories/polymarket.ts
|
|
530
492
|
var polymarket = {
|
|
531
|
-
/**
|
|
493
|
+
/** Returns trade and redemption activity for a Polymarket wallet. **Data refresh:** ~30 minutes */
|
|
532
494
|
activity: (params) => get("prediction-market/polymarket/activity", params),
|
|
533
|
-
/**
|
|
495
|
+
/** Returns Polymarket events with nested markets, optionally filtered by `event_slug`. Each event includes aggregated status, volume, and a list of markets with `side_a`/`side_b` outcomes. **Data refresh:** ~30 minutes */
|
|
534
496
|
events: (params) => get("prediction-market/polymarket/events", params),
|
|
535
|
-
/**
|
|
497
|
+
/** Returns Polymarket markets, optionally filtered by `market_slug`. Each market includes `side_a` and `side_b` outcomes. Current prices are available via `/polymarket/prices` using the `condition_id`. **Data refresh:** ~30 minutes */
|
|
536
498
|
markets: (params) => get("prediction-market/polymarket/markets", params),
|
|
537
|
-
/**
|
|
499
|
+
/** Returns daily open interest history for a Polymarket market. **Data refresh:** ~30 minutes */
|
|
538
500
|
open_interest: (params) => get("prediction-market/polymarket/open-interest", params),
|
|
539
|
-
/**
|
|
501
|
+
/** Returns wallet positions on Polymarket markets. **Data refresh:** ~30 minutes */
|
|
540
502
|
positions: (params) => get("prediction-market/polymarket/positions", params),
|
|
541
|
-
/**
|
|
503
|
+
/** Returns aggregated price history for a Polymarket market. Use `interval=latest` for the most recent price snapshot. **Data refresh:** ~30 minutes */
|
|
542
504
|
prices: (params) => get("prediction-market/polymarket/prices", params),
|
|
543
|
-
/**
|
|
505
|
+
/** Returns top-ranked Polymarket markets. **Sort by:** `volume_24h`, `volume_7d`, `open_interest`, or `trade_count`. **Filters:** `status` and `end_before`. **Data refresh:** ~30 minutes */
|
|
544
506
|
ranking: (params) => get("prediction-market/polymarket/ranking", params),
|
|
545
|
-
/**
|
|
507
|
+
/** Returns paginated trade records for a Polymarket market or wallet. **Filters:** `condition_id` (market) or `address` (wallet), plus `outcome_label`, `min_amount`, and date range. At least one of `condition_id` or `address` is required. **Sort:** `newest`, `oldest`, or `largest`. **Data refresh:** ~30 minutes */
|
|
546
508
|
trades: (params) => get("prediction-market/polymarket/trades", params),
|
|
547
|
-
/**
|
|
509
|
+
/** Returns trading volume and trade count history for a Polymarket market. **Data refresh:** ~30 minutes */
|
|
548
510
|
volumes: (params) => get("prediction-market/polymarket/volumes", params)
|
|
549
511
|
};
|
|
550
512
|
|
|
551
513
|
// src/data/categories/prediction_market.ts
|
|
552
514
|
var prediction_market = {
|
|
553
|
-
/**
|
|
515
|
+
/** Returns daily notional volume and open interest aggregated by category across Kalshi and Polymarket. **Filters:** `source` or `category`. **Data refresh:** daily */
|
|
554
516
|
category_metrics: (params) => get("prediction-market/category-metrics", params)
|
|
555
517
|
};
|
|
556
518
|
|
|
557
519
|
// src/data/categories/project.ts
|
|
558
520
|
var project = {
|
|
559
|
-
/**
|
|
521
|
+
/** Returns time-series DeFi metrics for a project. **Available metrics:** `volume`, `fee`, `fees`, `revenue`, `tvl`, `users`. **Lookup:** by UUID (`id`) or name (`q`). Filter by `chain` and date range (`from`/`to`). Returns 404 if the project is not found. **Note:** this endpoint only returns data for DeFi protocol projects (e.g. `aave`, `uniswap`, `lido`, `makerdao`). Use `q` with a DeFi protocol name. */
|
|
560
522
|
defi_metrics: (params) => get("project/defi/metrics", params),
|
|
561
|
-
/**
|
|
523
|
+
/** Returns top DeFi projects ranked by a protocol metric. **Available metrics:** `tvl`, `revenue`, `fees`, `volume`, `users`. */
|
|
562
524
|
defi_ranking: (params) => get("project/defi/ranking", params),
|
|
563
|
-
/**
|
|
525
|
+
/** Returns multiple project sub-resources in a single request. **Available fields** (via `fields`): `overview`, `token_info`, `tokenomics`, `funding`, `team`, `contracts`, `social`, `tge_status`. **Lookup:** accepts project names directly via `q` (e.g. `?q=aave`) — no need to call `/search/project` first. Also accepts UUID via `id`. Returns 404 if not found. For DeFi metrics (TVL, fees, revenue, volume, users) and per-chain breakdown, use `/project/defi/metrics`. */
|
|
564
526
|
detail: (params) => get("project/detail", params)
|
|
565
527
|
};
|
|
566
528
|
|
|
567
529
|
// src/data/categories/search.ts
|
|
568
530
|
var search = {
|
|
569
|
-
/**
|
|
531
|
+
/** Searches and filters airdrop opportunities. **Filters:** keyword, status, reward type, task type. Returns paginated results with optional task details. */
|
|
570
532
|
airdrop: (params) => get("search/airdrop", params),
|
|
571
|
-
/**
|
|
533
|
+
/** Searches project events by keyword, optionally filtered by `type`. **Valid types:** `launch`, `upgrade`, `partnership`, `news`, `airdrop`, `listing`, `twitter`. **Lookup:** by UUID (`id`) or name (`q`). Returns 404 if the project is not found. */
|
|
572
534
|
events: (params) => get("search/events", params),
|
|
573
|
-
/**
|
|
535
|
+
/** Searches funds by keyword. **Included fields:** name, tier, type, logo, top invested projects. */
|
|
574
536
|
fund: (params) => get("search/fund", params),
|
|
575
|
-
/**
|
|
537
|
+
/** Searches Kalshi events by keyword and/or category. **Filters:** - Keyword matching event title, subtitle, or market title - Category At least one of `q` or `category` is required. Returns events with nested markets. **Data refresh:** ~30 minutes */
|
|
576
538
|
kalshi: (params) => get("search/kalshi", params),
|
|
577
|
-
/**
|
|
539
|
+
/** Searches crypto news articles by keyword. Returns top 10 results ranked by relevance with highlighted matching fragments. */
|
|
578
540
|
news: (params) => get("search/news", params),
|
|
579
|
-
/**
|
|
541
|
+
/** Searches Polymarket events by keyword, tags, and/or category. **Filters:** - Keyword matching market question, event title, or description - Comma-separated tag labels - Surf-curated category At least one of `q`, `tags`, or `category` is required. Returns events with nested markets ranked by volume. **Data refresh:** ~30 minutes */
|
|
580
542
|
polymarket: (params) => get("search/polymarket", params),
|
|
581
|
-
/**
|
|
543
|
+
/** Searches crypto projects by keyword. **Included fields:** name, description, chains, logo. */
|
|
582
544
|
project: (params) => get("search/project", params),
|
|
583
|
-
/**
|
|
545
|
+
/** Searches X (Twitter) users by keyword. **Included fields:** handle, display name, bio, follower count, avatar. */
|
|
584
546
|
social_people: (params) => get("search/social/people", params),
|
|
585
|
-
/**
|
|
547
|
+
/** Searches X (Twitter) posts by keyword or `from:handle` syntax. **Included fields:** author, content, engagement metrics, timestamp. **Pagination:** check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request. */
|
|
586
548
|
social_posts: (params) => get("search/social/posts", params),
|
|
587
|
-
/**
|
|
549
|
+
/** Searches wallets by ENS name, address label, or address prefix. Returns matching wallet addresses with entity labels. */
|
|
588
550
|
wallet: (params) => get("search/wallet", params),
|
|
589
|
-
/**
|
|
551
|
+
/** Searches web pages, articles, and content by keyword. **Filters:** domain via `site` (e.g. `coindesk.com`). **Included fields:** titles, URLs, content snippets. */
|
|
590
552
|
web: (params) => get("search/web", params)
|
|
591
553
|
};
|
|
592
554
|
|
|
593
555
|
// src/data/categories/social.ts
|
|
594
556
|
var social = {
|
|
595
|
-
/**
|
|
557
|
+
/** Returns a **point-in-time snapshot** of social analytics for a project. **Available fields** (via `fields`): `sentiment`, `follower_geo`, `smart_followers`. **Lookup:** by X account ID (`x_id`) or project name (`q`, e.g. `uniswap`, `solana`). The `q` parameter must be a crypto project name, not a personal Twitter handle. Returns 404 if the project has no linked Twitter account. For sentiment **trends over time**, use `/social/mindshare` instead. */
|
|
596
558
|
detail: (params) => get("social/detail", params),
|
|
597
|
-
/**
|
|
559
|
+
/** Returns mindshare (social view count) **time-series trend** for a project, aggregated by `interval`. **Intervals:** `5m`, `1h`, `1d`, `7d`. **Filters:** date range with `from`/`to` (Unix seconds). Lookup by name (`q`). Use this for sentiment **trends**, mindshare **over time**, or social momentum changes. For a **point-in-time snapshot** of social analytics (sentiment score, follower geo, smart followers), use `/social/detail` instead. */
|
|
598
560
|
mindshare: (params) => get("social/mindshare", params),
|
|
599
|
-
/**
|
|
561
|
+
/** Returns top crypto projects ranked by mindshare (social view count), refreshed every 5 minutes. **Filters:** - `tag` — scope to a category (e.g. `dex`, `l1`, `meme`) - `time_range` — ranking window (`24h`, `48h`, `7d`, `30d`) Supports `limit`/`offset` pagination. */
|
|
600
562
|
ranking: (params) => get("social/ranking", params),
|
|
601
|
-
/**
|
|
563
|
+
/** Returns smart follower count time-series for a project, sorted by date descending. **Lookup:** by X account ID (`x_id`) or project name (`q`). The `q` parameter must be a project name (e.g. `uniswap`, `ethereum`), not a personal X handle — use `x_id` for individual accounts. Returns 404 if the project has no linked X account. */
|
|
602
564
|
smart_followers_history: (params) => get("social/smart-followers/history", params),
|
|
603
|
-
/** Returns replies/comments on a specific tweet. Lookup by `tweet_id`. */
|
|
565
|
+
/** Returns replies/comments on a specific tweet. **Lookup:** by `tweet_id`. */
|
|
604
566
|
tweet_replies: (params) => get("social/tweet/replies", params),
|
|
605
|
-
/**
|
|
567
|
+
/** Returns X (Twitter) posts by numeric post ID strings. Pass up to 100 comma-separated IDs via the `ids` query parameter. */
|
|
606
568
|
tweets: (params) => get("social/tweets", params),
|
|
607
|
-
/**
|
|
569
|
+
/** Returns an X (Twitter) user profile. **Included fields:** display name, follower count, following count, and bio. **Lookup:** by `handle` (without @). */
|
|
608
570
|
user: (params) => get("social/user", params),
|
|
609
|
-
/** Returns a list of followers for the specified handle on X (Twitter). Lookup by `handle` (without @). */
|
|
571
|
+
/** Returns a list of followers for the specified handle on X (Twitter). **Lookup:** by `handle` (without @). */
|
|
610
572
|
user_followers: (params) => get("social/user/followers", params),
|
|
611
|
-
/** Returns a list of users that the specified handle follows on X (Twitter). Lookup by `handle` (without @). */
|
|
573
|
+
/** Returns a list of users that the specified handle follows on X (Twitter). **Lookup:** by `handle` (without @). */
|
|
612
574
|
user_following: (params) => get("social/user/following", params),
|
|
613
|
-
/**
|
|
575
|
+
/** Returns recent X (Twitter) posts by a specific user, ordered by recency. **Lookup:** by `handle` (without @). Use `filter=original` to exclude retweets. **Pagination:** check `meta.has_more`; if true, pass `meta.next_cursor` as the `cursor` query parameter in the next request. */
|
|
614
576
|
user_posts: (params) => get("social/user/posts", params),
|
|
615
|
-
/** Returns recent replies by the specified handle on X (Twitter). Lookup by `handle` (without @). */
|
|
577
|
+
/** Returns recent replies by the specified handle on X (Twitter). **Lookup:** by `handle` (without @). */
|
|
616
578
|
user_replies: (params) => get("social/user/replies", params)
|
|
617
579
|
};
|
|
618
580
|
|
|
619
581
|
// src/data/categories/token.ts
|
|
620
582
|
var token = {
|
|
621
|
-
/**
|
|
583
|
+
/** Returns recent DEX swap events for a token contract address. **Covered DEXes:** `uniswap`, `sushiswap`, `curve`, `balancer`. **Included fields:** trading pair, amounts, USD value, taker address. **Data refresh:** ~24 hours · **Chains:** Ethereum, Base */
|
|
622
584
|
dex_trades: (params) => get("token/dex-trades", params),
|
|
623
|
-
/**
|
|
585
|
+
/** Returns top token holders for a contract address. **Included fields:** wallet address, balance, and percentage. **Lookup:** by `address` and `chain`. Supports EVM chains and Solana. */
|
|
624
586
|
holders: (params) => get("token/holders", params),
|
|
625
|
-
/**
|
|
587
|
+
/** Returns token unlock time-series with amounts and allocation breakdowns. **Lookup:** by project UUID (`id`) or token `symbol`. Filter by date range with `from`/`to` — defaults to the current calendar month when omitted. Returns 404 if no token found. */
|
|
626
588
|
tokenomics: (params) => get("token/tokenomics", params),
|
|
627
|
-
/**
|
|
589
|
+
/** Returns recent transfer events **for a specific token** (ERC-20/TRC-20 contract). Pass the **token contract address** in `address` — returns every on-chain transfer of that token regardless of sender/receiver. **Included fields:** sender, receiver, raw amount, block timestamp. Use this to analyze a token's on-chain activity (e.g. large movements, distribution patterns). **Lookup:** `address` (token contract) + `chain`. Sort by `asc` or `desc`. **Data refresh:** ~24 hours · **Chains:** Ethereum, Base, TRON (Solana uses a different source with no delay) */
|
|
628
590
|
transfers: (params) => get("token/transfers", params)
|
|
629
591
|
};
|
|
630
592
|
|
|
593
|
+
// src/data/categories/v2.ts
|
|
594
|
+
var v2 = {
|
|
595
|
+
/** Historical orderbook snapshots for a Kalshi market. Returns yes-side bid/ask levels. Timestamps in milliseconds, prices in cents. Data refresh: ~5 minutes */
|
|
596
|
+
kalshi_orderbooks: (params) => get("gateway/v2/kalshi/orderbooks", params),
|
|
597
|
+
/** OHLCV candlestick data for a Polymarket market. Prices normalized to YES side. Data refresh: ~30 minutes */
|
|
598
|
+
polymarket_candlesticks: (params) => get("gateway/v2/polymarket/candlesticks/{condition_id}", params),
|
|
599
|
+
/** Cumulative volume time series for a Polymarket token. Data refresh: ~30 minutes */
|
|
600
|
+
polymarket_volume_timeseries: (params) => get("gateway/v2/polymarket/markets/{token_id}/volume", params),
|
|
601
|
+
/** Historical orderbook snapshots for a Polymarket token. Returns raw bid/ask depth levels. Timestamps in milliseconds. Data refresh: ~5 minutes */
|
|
602
|
+
polymarket_orderbooks: (params) => get("gateway/v2/polymarket/orderbooks", params),
|
|
603
|
+
/** Volume breakdown by outcome (YES/NO) for a Polymarket market. Data refresh: ~30 minutes */
|
|
604
|
+
polymarket_volume_chart: (params) => get("gateway/v2/polymarket/volume-chart/{condition_id}", params)
|
|
605
|
+
};
|
|
606
|
+
|
|
631
607
|
// src/data/categories/wallet.ts
|
|
632
608
|
var wallet = {
|
|
633
|
-
/**
|
|
609
|
+
/** Returns multiple wallet sub-resources in a single request. **Available fields** (via `fields`): `balance`, `tokens`, `labels`, `nft`. **Lookup:** by `address`. Partial failures return available fields with per-field error info. Returns 422 if `fields` is invalid. */
|
|
634
610
|
detail: (params) => get("wallet/detail", params),
|
|
635
|
-
/**
|
|
611
|
+
/** Returns full transaction history for a wallet — swaps, transfers, and contract interactions. **Lookup:** by `address`. Filter by `chain` — supports `ethereum`, `polygon`, `bsc`, `arbitrum`, `optimism`, `avalanche`, `fantom`, `base`. */
|
|
636
612
|
history: (params) => get("wallet/history", params),
|
|
637
|
-
/**
|
|
613
|
+
/** Returns entity labels for multiple wallet addresses. Pass up to 100 comma-separated addresses via the `addresses` query parameter. **Included fields:** entity name, type, and labels per address. */
|
|
638
614
|
labels_batch: (params) => get("wallet/labels/batch", params),
|
|
639
|
-
/**
|
|
615
|
+
/** Returns a time-series of the wallet's total net worth in USD. Returns ~288 data points at 5-minute intervals covering the last 24 hours. Fixed window — no custom time range supported. */
|
|
640
616
|
net_worth: (params) => get("wallet/net-worth", params),
|
|
641
|
-
/**
|
|
617
|
+
/** Returns all DeFi protocol positions for a wallet — lending, staking, LP, and farming with token breakdowns and USD values. **Lookup:** by `address`. */
|
|
642
618
|
protocols: (params) => get("wallet/protocols", params),
|
|
643
|
-
/**
|
|
619
|
+
/** Returns recent token transfers **sent or received by a wallet**. Pass the **wallet address** in `address` — returns all ERC-20/SPL token transfers where this wallet is the sender or receiver. **Included fields:** token contract, counterparty, raw amount, block timestamp. Use this to audit a wallet's token flow (e.g. inflows, outflows, airdrop receipts). **Lookup:** `address` (wallet, raw 0x hex or base58 — ENS not supported). Filter by `chain` — supports `ethereum`, `base`, `solana`. **Data refresh:** ~24 hours · **Chains:** Ethereum, Base (Solana uses a different source with no delay) */
|
|
644
620
|
transfers: (params) => get("wallet/transfers", params)
|
|
645
621
|
};
|
|
646
622
|
|
|
647
623
|
// src/data/categories/web.ts
|
|
648
624
|
var web = {
|
|
649
|
-
/**
|
|
625
|
+
/** Fetches a web page and converts it to clean, LLM-friendly markdown. **Options:** - `target_selector` — extract specific page sections - `remove_selector` — strip unwanted elements Returns 400 if the URL is invalid or unreachable. */
|
|
650
626
|
fetch: (params) => get("web/fetch", params)
|
|
651
627
|
};
|
|
652
628
|
|
|
@@ -660,6 +636,7 @@ var dataApi = {
|
|
|
660
636
|
fund,
|
|
661
637
|
kalshi,
|
|
662
638
|
market,
|
|
639
|
+
matching,
|
|
663
640
|
news,
|
|
664
641
|
onchain,
|
|
665
642
|
polymarket,
|
|
@@ -668,6 +645,7 @@ var dataApi = {
|
|
|
668
645
|
search,
|
|
669
646
|
social,
|
|
670
647
|
token,
|
|
648
|
+
v2,
|
|
671
649
|
wallet,
|
|
672
650
|
web
|
|
673
651
|
};
|