MetEngine Data Agent API – Complete Skill File

Integrate with MetEngine's real-time smart money analytics API for advanced trading insights.

This is the authoritative skill manifest for Claude Code agents working with MetEngine's real-time smart money analytics API.

Core Service Details

MetEngine Data Agent provides 63 endpoints spanning three platforms:

  • Polymarket (27 endpoints): prediction market analytics
  • Hyperliquid (18 endpoints): perpetual futures trader intelligence
  • Meteora (18 endpoints): Solana LP/AMM pool analytics

Base URL: https://agent.metengine.xyz

Payment: x402 protocol on Solana Mainnet (USDC). No API keys required—payment IS authentication.

Quick Start: Session Memory System

Before making any API call, check for ~/.claude/agents/metengine-memory.md. This persistent file eliminates repetitive setup and saves ~80% of setup tokens by storing:

  • Wallet keypair path and public address (never the private key)
  • Confirmed installed packages (@x402/core, @x402/svm, @solana/kit)
  • Working bootstrap code snippet (copy-paste ready)
  • Endpoint performance history (timeouts, fallbacks, costs)
  • Quirks and known issues

Update rules:

  1. After first successful setup -> record wallet, packages, bootstrap code
  2. After every API call -> append to Endpoint History (keep last 10 rows)
  3. When using a fallback -> record in Fallbacks Learned section
  4. At session end -> update Last Updated timestamp

New agents: Create the memory file after initial onboarding. Returning agents: Read memory first, skip setup if installed: true.

Payment Flow (x402 on Solana Mainnet)

All paid endpoints follow a two-step handshake:

Step 1 (Agent -> API): Send initial request

  • Returns: 402 Payment Required with encoded price

Step 2 (Agent -> Solana -> API): Sign and re-send

  • Agent signs payment locally using @x402/core
  • Sends second request with PAYMENT-SIGNATURE header
  • API verifies on-chain, executes query, settles payment
  • Returns: 200 with data + settlement proof (tx hash)

Key rule: Payment only settles on successful 2xx responses. Timeouts and errors incur no charge.

Client Bootstrap (TypeScript/Bun)

import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { toClientSvmSigner } from "@x402/svm";
import { getBase58Encoder, createKeyPairSignerFromBytes } from "@solana/kit";

const bytes = getBase58Encoder().encode(process.env.SOLANA_PRIVATE_KEY!);
const signer = await createKeyPairSignerFromBytes(bytes);
const client = new x402Client();
registerExactSvmScheme(client, { signer: toClientSvmSigner(signer) });
const httpClient = new x402HTTPClient(client);
const BASE_URL = "https://agent.metengine.xyz";

async function paidFetch(path, options = {}) {
  const url = `${BASE_URL}${path}`;
  const initial = await fetch(url, options);
  if (initial.status !== 402) throw new Error(`Expected 402, got ${initial.status}`);

  const paymentRequired = httpClient.getPaymentRequiredResponse(
    (name) => initial.headers.get(name), await initial.json()
  );
  const price = Number(paymentRequired.accepts[0].amount);

  const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
  const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);

  const paid = await fetch(url, { ...options, headers: { ...paymentHeaders } });
  if (paid.status !== 200) throw new Error(`Payment failed: ${paid.status}`);

  const settlement = httpClient.getPaymentSettleResponse((name) => paid.headers.get(name));
  return { data: (await paid.json()).data, settlement, price };
}

Install dependencies: bun add @x402/core @x402/svm @solana/kit

Pricing Structure

All prices in USDC on Solana Mainnet. Pricing endpoint (free, no payment):

GET https://agent.metengine.xyz/api/v1/pricing

Tier base costs:

  • Light: $0.01
  • Medium: $0.02
  • Heavy: $0.05
  • Whale: $0.08

Multipliers applied:

  • Timeframe: 0.5x (1h) to 5.0x (365d/all)
  • Limit scaling: max(1, requested_limit / default_limit)
  • Category filter: 0.7x discount
  • Condition_id / pool_address filter: 0.5x discount
  • Smart_money_only: 0.7x discount

Hard caps: Floor $0.01 per request, ceiling $0.20 per request.

Special endpoints: /markets/opportunities capped at $0.15; /wallets/copy-traders capped at $0.12.

Health & Monitoring

GET https://agent.metengine.xyz/health

Free endpoint. Returns component status (ClickHouse, Postgres, Redis), active request count, semaphore limits, and error stats.

Display Rule: Full Addresses Always

Never truncate or trim wallet/contract addresses. Always show full addresses (e.g. 0x61276aba49117fd9299707d5d573652949d5c977, not 0x6127...c977). This applies to all hex addresses (Polymarket, Hyperliquid), base58 pubkeys (Meteora), condition_ids, token_ids, and tx hashes.

Polymarket (27 Endpoints)

#TierPathPurpose
1MGET /api/v1/markets/trendingVolume spikes, timeframe filter
2LGET /api/v1/markets/searchKeyword/category/status, accepts Polymarket URLs
3LGET /api/v1/markets/categoriesList categories with activity stats
4LGET /api/v1/platform/statsPlatform aggregates (volume, trades, wallets)
5HPOST /api/v1/markets/intelligenceSmart money consensus, top wallets, signal analysis
6LGET /api/v1/markets/price-historyOHLCV time series per outcome
7MPOST /api/v1/markets/sentimentSentiment time series with smart money overlay
8MPOST /api/v1/markets/participantsParticipant distribution by tier
9HPOST /api/v1/markets/insiders7-signal behavioral insider detection
10LGET /api/v1/markets/tradesChronological trade feed, side/min_usdc filter
11WGET /api/v1/markets/similarRelated markets by wallet overlap
12WGET /api/v1/markets/opportunitiesSmart money vs price disagreement
13HGET /api/v1/markets/high-convictionHigh-conviction bets (fallback for #12)
14MGET /api/v1/markets/capital-flowSector rotation, smart_money_only filter
15MGET /api/v1/trades/whalesLarge trades, condition_id/category filter
16MGET /api/v1/markets/volume-heatmapVolume by category/hour/day
17HPOST /api/v1/wallets/profileFull dossier: score, positions, trades
18MPOST /api/v1/wallets/activityRecent activity by timeframe
19MPOST /api/v1/wallets/pnl-breakdownPer-market PnL with best/worst trades
20WPOST /api/v1/wallets/compare2-5 wallets side-by-side
21WPOST /api/v1/wallets/copy-tradersDetect lag, detect overlap (max $0.12)
22HGET /api/v1/wallets/top-performersLeaderboard (2x penalty without category)
23HGET /api/v1/wallets/niche-expertsCategory specialists
24LGET /api/v1/markets/resolutionsResolved markets + smart money accuracy
25HGET /api/v1/wallets/alpha-callersEarly traders on trending markets
26MGET /api/v1/markets/dumb-moneyLow-score positions (contrarian)
27HGET /api/v1/wallets/insidersGlobal insider candidates

Key quirks:

  • Wallet addresses MUST be lowercase.
  • /trades/whales returns REDEEM trades (resolved payouts) with price=1.00, side=REDEEM. Filter by side=BUY|SELL to exclude.
  • /markets/opportunities (504) -> fallback to /markets/high-conviction.
  • Price = implied probability (0 to 1).

Hyperliquid (18 Endpoints)

#TierPathPurpose
28LGET /api/v1/hl/platform/statsPlatform aggregates
29MGET /api/v1/hl/coins/trendingTrending by activity (use 7d if 24h empty)
30LGET /api/v1/hl/coins/listAll coins with 7d stats
31MGET /api/v1/hl/coins/volume-heatmapVolume by coin/hour
32HGET /api/v1/hl/traders/leaderboardRanked by PnL/ROI/Sharpe/win_rate
33HPOST /api/v1/hl/traders/profileFull dossier (intermittent 500, use fallback)
34WPOST /api/v1/hl/traders/compare2-5 traders
35MGET /api/v1/hl/traders/daily-pnlDaily time series with streak tracking
36MPOST /api/v1/hl/traders/pnl-by-coinPer-coin PnL (realized only)
37HGET /api/v1/hl/traders/fresh-whalesNew accounts with high volume
38MGET /api/v1/hl/trades/whalesLarge trades, direction filter
39LGET /api/v1/hl/trades/feedChronological feed per coin
40MGET /api/v1/hl/trades/long-short-ratioDirectional ratio (returns zeros, reconstruct)
41LGET /api/v1/hl/smart-wallets/listSmart wallet ranking
42MGET /api/v1/hl/smart-wallets/activityRecent smart wallet trades
43HGET /api/v1/hl/smart-wallets/signalsDirectional signals by coin (use 7d if 24h empty)
44HGET /api/v1/hl/pressure/pairsLong/short pressure with positions
45MGET /api/v1/hl/pressure/summaryCross-coin pressure snapshot

Key quirks:

  • timeframe=24h on endpoints #29, #43 often empty -> use timeframe=7d.
  • /hl/traders/profile (500) -> fallback to /hl/traders/leaderboard + /hl/traders/pnl-by-coin.
  • /hl/trades/long-short-ratio returns zeros -> reconstruct from /hl/trades/whales by counting side volume.
  • Coin symbols uppercase only: BTC, not BTC-USDC.
  • Trader addresses are 0x hex (case-insensitive).
  • Realized PnL only (no unrealized).
  • Smart threshold: score >= 85.

Meteora (18 Endpoints)

#TierPathPurpose
46MGET /api/v1/meteora/pools/trendingVolume spikes (deduplicate by pool_address)
47MGET /api/v1/meteora/pools/topTop by volume/LP count/fees
48LGET /api/v1/meteora/pools/searchSearch by address or token name
49MGET /api/v1/meteora/pools/detailFull pool metadata
50LGET /api/v1/meteora/pools/volume-historyVolume time series
51LGET /api/v1/meteora/pools/eventsChronological event feed
52MGET /api/v1/meteora/pools/fee-analysisFee claiming breakdown
53HGET /api/v1/meteora/lps/topLP leaderboard (sort=volume, avoid sort=fees)
54HPOST /api/v1/meteora/lps/profileFull LP dossier
55MGET /api/v1/meteora/lps/whalesLarge LP events
56WPOST /api/v1/meteora/lps/compare2-5 LPs
57MGET /api/v1/meteora/positions/activeActive LP positions
58LGET /api/v1/meteora/positions/historyPosition events (DLMM only)
59LGET /api/v1/meteora/platform/statsPlatform aggregates
60MGET /api/v1/meteora/platform/volume-heatmapVolume by action/hour
61LGET /api/v1/meteora/platform/metengine-shareRouting share %
62MGET /api/v1/meteora/dca/pressureToken accumulation pressure
63HGET /api/v1/meteora/pools/smart-walletPools with highest smart LP activity

Key quirks:

  • /meteora/lps/top?sort_by=fees (500) -> fallback to sort_by=volume.
  • DAMM v2 pools show high fee rates (30-50%) on new token launches -- separate from DLMM and flag.
  • DLMM: token_x/token_y, PascalCase events (AddLiquidity, RemoveLiquidity).
  • DAMM v2: token_a/token_b, snake_case events (add_liquidity, remove_liquidity).
  • Addresses are Solana base58 pubkeys (case-sensitive).

Performance Benchmarks

MetricValue
p50 latency800ms
p95 latency3s
p99 latency8s
Handler timeout60s (no charge)
Payment verification timeout5s
Max concurrent paid requests50

Data freshness:

  • Polymarket trades: sub-minute
  • Polymarket wallet scores: daily
  • Hyperliquid trades: sub-minute
  • Hyperliquid smart scores: continuous (formula-based)
  • Meteora events: sub-minute
  • Meteora LP scores: daily

Error Handling & Fallbacks

StatusCauseRecovery
400Invalid paramsValidate request JSON/query string
402Payment verification failedCheck signer/nonce; sign and retry
404Path not foundVerify endpoint in this document
429Rate limitBack off and retry
500Server errorRetry once; use fallback endpoint
503Capacity or payment service downCheck Retry-After header
504Query timeout (no charge)Narrow params or use fallback

Fallback map:

  • /markets/opportunities (504) -> /markets/high-conviction
  • /wallets/top-performers (503 on 7d) -> try timeframe=24h
  • /markets/insiders (timeout) -> /markets/trades with condition_id filter
  • /hl/coins/trending?timeframe=24h (empty) -> timeframe=7d
  • /hl/traders/profile (500) -> /hl/traders/leaderboard + /hl/traders/pnl-by-coin
  • /hl/trades/long-short-ratio (zeros) -> reconstruct from /hl/trades/whales
  • /meteora/lps/top?sort_by=fees (500) -> sort_by=volume

Skill File Updates

Download latest weekly:

curl -sL https://www.metengine.xyz/skill.md -o .claude/agents/metengine-data-agent.md

Current version: 1.0.0

Wallet Security

  • NEVER log, print, or display keypair file contents.
  • ONLY store keypair file path and public address (base58) in memory.
  • Load keypair at runtime directly into the signer without intermediate variables.

What This API Does NOT Provide

  1. Trade execution (read-only)
  2. Real-time WebSocket streams
  3. Historical backfill on demand
  4. Unrealized PnL for Hyperliquid
  5. Mark-to-market valuation for Meteora positions
  6. Polymarket order book depth
  7. Custom scoring models
  8. Cross-platform wallet linking
  9. Token price feeds (use oracle for that)
  10. Any endpoints beyond these 63

Example Workflow: Analyze a Polymarket Market

const { data: markets } = await paidFetch(
  "/api/v1/markets/search?query=bitcoin&limit=5"
); // $0.01

const market = markets[0];
const { data: intel } = await paidFetch("/api/v1/markets/intelligence", {
  method: "POST",
  body: { condition_id: market.condition_id, top_n_wallets: 10 }
}); // $0.05

const { data: history } = await paidFetch(
  `/api/v1/markets/price-history?condition_id=${market.condition_id}&timeframe=7d`
); // $0.01

console.log(`Smart money favors: ${intel.smart_money.consensus_outcome}`);
console.log(`Total: $0.07 USDC spent, ~5 seconds`);

This document is current as of version 1.0.0. Check for updates weekly.