X402 Sample Bot

MetEngine Data Agent API – Complete Skill File

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)

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)

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)

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

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

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.