API Status: Operational
Get Started in 30 Seconds
1
Discover Capabilities
curl https://degenai.dev/x402
2
Query Any Wallet (FREE)
curl -X POST https://degenai.dev/x402/get_positions \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x..."}'
3
Ready to Trade?
Complete one-time authorization below, then execute trades with pay-per-use pricing.
Why DegenAI x402?
HTTP Simple HTTP API No SDK required. Works with any language that can make HTTP requests.
$ Pay Per Use $0.10 + 0.01% per trade. No subscriptions, no API keys to manage.
4% Fee Discount Automatic 4% HyperLiquid fee reduction on all trades.
IPFS IPFS Receipts Permanent audit trail for every trade stored on IPFS.
FREE FREE Queries Positions, orders, history - query any wallet at no charge.
NET Multi-Network Pay with USDC (Base) or USDM (MegaETH).
x402 Protocol
x402 enables pay-per-use trading for AI agents. Built on HTTP 402 Payment Required semantics, it allows any agent to execute HyperLiquid trades with cryptographic payment verification.
Supported Networks
Network Chain ID Asset x402 Asset
Base 8453 USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
MegaETH 4326 USDM 0x2c2d8EF0664432BA243deF0b8f60aF7aB43a60B4
Discovery Endpoint
The discovery endpoint returns all available capabilities, pricing, health status, and integration documentation:
GET https://degenai.dev/x402

# Response includes:
# - capabilities: Available operations with pricing
# - serviceHealth: HyperLiquid, Meridian, MegaETH status
# - authorization: FREE auth endpoints
# - docs: Integration guide
Authorization Flow (FREE)
One-time setup per wallet. No payment required.
Two wallets, two roles. Most integrations use two separate keys:
Wallet Field Signs Purpose
Payer wallet payerAddress EIP-3009 payment signatures Holds USDC/USDM, pays per-trade fees
Trading wallet hyperLiquidWallet EIP-712 agent approval + builder fee Executes trades on HyperLiquid
These can be the same address if you use one wallet for both payment and trading.
1
Prepare Authorization
POST /x402/authorize/prepare
Content-Type: application/json

{
  "payerAddress": "0xYourPayerWallet",
  "hyperLiquidWallet": "0xYourTradingWallet"
}
Returns EIP-712 typed data for signing: agentApprovalTypedData and builderFeeTypedData (if builder fee is enabled). Also returns nonce and builderNonce (both long integers) — pass these back in the approve step.
2
Sign the Typed Data
// Sign BOTH with your HyperLiquid trading wallet
const agentSig = await wallet.signTypedData(
  agentApprovalTypedData.domain,
  agentApprovalTypedData.types,
  agentApprovalTypedData.message
);

// Builder fee signature (only if builderFeeTypedData is present)
const builderSig = builderFeeTypedData
  ? await wallet.signTypedData(
      builderFeeTypedData.domain,
      builderFeeTypedData.types,
      builderFeeTypedData.message
    )
  : '';
3
Approve Authorization
POST /x402/authorize/approve
Content-Type: application/json

{
  "payerAddress": "0xYourPayerWallet",
  "hyperLiquidWallet": "0xYourTradingWallet",
  "agentApprovalSignature": "0xAgentApprovalSig...",
  "builderFeeSignature": "0xBuilderFeeSig...",
  "nonce": 1234567890,
  "builderNonce": 1234567891
}
Both signatures are EIP-712 — sign with your trading wallet (hyperLiquidWallet). nonce and builderNonce are long integers from the prepare response.
Verify Authorization Status
GET /x402/authorize/status?payerAddress=0xYourPayerWallet
FREE Capabilities
Query any HyperLiquid wallet at no charge. No authorization required for read-only operations.
get_positions FREE
Query active perpetual positions for any wallet
curl -X POST https://degenai.dev/x402/get_positions \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x..."}'
Example Response
{
  "success": true,
  "message": "Found 2 active position(s)",
  "data": {
    "positions": [
      {
        "coin": "ETH",
        "size": "0.5",
        "entryPrice": "2500.00",
        "unrealizedPnl": "125.50"
      }
    ],
    "count": 2,
    "wallet": "0x...",
    "accountValue": "1250.50"
  }
}
get_open_orders FREE
Query open (unfilled) orders
curl -X POST https://degenai.dev/x402/get_open_orders \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x..."}'
Example Response
{
  "success": true,
  "message": "Found 1 open order(s)",
  "data": {
    "orders": [
      {
        "coin": "ETH",
        "side": "buy",
        "size": "0.5",
        "price": "2400.00",
        "orderType": "limit",
        "orderId": "0x123..."
      }
    ],
    "count": 1,
    "wallet": "0x..."
  }
}
get_account_summary FREE
Portfolio overview with account value, margin, and leverage
curl -X POST https://degenai.dev/x402/get_account_summary \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x..."}'
Example Response
{
  "success": true,
  "data": {
    "accountValue": "10500.00",
    "marginUsed": "2100.00",
    "marginAvailable": "8400.00",
    "positionCount": 2,
    "openOrderCount": 1,
    "wallet": "0x..."
  }
}
get_trade_history FREE
Recent trade fills and execution history
curl -X POST https://degenai.dev/x402/get_trade_history \
  -H "Content-Type: application/json" \
  -d '{"wallet":"0x...", "limit": 20}'
Example Response
{
  "success": true,
  "message": "Found 20 trade(s)",
  "data": {
    "trades": [
      {
        "coin": "ETH",
        "side": "buy",
        "size": "0.5",
        "price": "2500.00",
        "fee": "0.25",
        "timestamp": "2026-02-10T12:00:00Z"
      }
    ],
    "count": 20,
    "wallet": "0x..."
  }
}
Caching: FREE queries return Cache-Control: max-age=5 (5 seconds). For real-time data, use HyperLiquid's WebSocket API directly.
Trading (Paid)
hyperliquid_order
Execute trades on HyperLiquid — create, modify, cancel, and close positions
Pricing
$0.10 + 0.01% of dollarSize
"Trade size" = the dollarSize parameter (USD notional). Example: $1,000 trade = $0.10 + $0.10 = $0.20 total. Use GET /x402/hyperliquid_order/pricing?dollarSize=1000 to preview exact fees.
Actions
The action field determines what the endpoint does. All actions below are sent to the same POST /x402/hyperliquid_order endpoint.
Action Description
create_marketMarket order (immediate execution)
create_limitLimit order at a specified price
create_stopStop/trigger order
create_batchMultiple orders in one request
modify_by_oidModify an order by HyperLiquid order ID
modify_by_cloidModify an order by client order ID
modify_batchModify multiple orders
cancel_by_oidCancel by HyperLiquid order ID
cancel_by_cloidCancel by client order ID
cancel_batchCancel multiple orders
Request Schema — Market Order
Field Type Required Description
actionstringYes"create_market"
coinstringYesAsset symbol, e.g. "ETH", "BTC"
isBuybooleanYestrue = long, false = short
dollarSizenumberYesOrder size in USD (min 1)
reduceOnlybooleanNoOnly reduce existing position (default: false)
takeProfitPricenumberNoAttach take-profit at this price
stopLossPricenumberNoAttach stop-loss at this price
cloidstringNoClient order ID (0x + 32 hex chars)
Request Schema — Limit Order
Same fields as market, plus:
Field Type Required Description
actionstringYes"create_limit"
pricenumberYesLimit price (must be > 0)
tifstringNoTime-in-force: "Gtc" (default), "Ioc", "Alo"
Request Schema — Cancel Order
Field Type Required Description
actionstringYes"cancel_by_oid" or "cancel_by_cloid"
coinstringYesAsset symbol
oidintegerCond.HyperLiquid order ID (for cancel_by_oid)
cloidstringCond.Client order ID (for cancel_by_cloid)
Closing a position: Use create_market with "reduceOnly": true and the opposite isBuy direction. For partial close, set dollarSize to the amount you want to close.
Field aliases: Snake-case variants are accepted — dollar_size, is_buy, reduce_only, trigger_price, take_profit_price, stop_loss_price, etc.
Payment Flow
1. Create EIP-3009 TransferWithAuthorization signature for payment amount
2. Base64 encode the payment payload
3. Include as PAYMENT-SIGNATURE header
4. Response includes IPFS receipt CID for verification
Example: Market Buy
POST /x402/hyperliquid_order
Content-Type: application/json
PAYMENT-SIGNATURE: base64EncodedPaymentSignature

{
  "action": "create_market",
  "coin": "ETH",
  "isBuy": true,
  "dollarSize": 100
}
Example Response
{
  "success": true,
  "message": "Order executed successfully",
  "data": {
    "orderIds": ["1234567890"],
    "orderCount": 1,
    "action": "CREATE_MARKET",
    "ipfsCid": "QmXyz...",
    "ipfsUrl": "https://gateway.pinata.cloud/ipfs/QmXyz..."
  },
  "requestId": "req_abc123",
  "executedAt": "2026-02-10T12:00:00Z"
}
Example: Cancel Order
POST /x402/hyperliquid_order
Content-Type: application/json
PAYMENT-SIGNATURE: base64EncodedPaymentSignature

{
  "action": "cancel_by_oid",
  "coin": "ETH",
  "oid": 1234567890
}
Example: Close Position
POST /x402/hyperliquid_order
Content-Type: application/json
PAYMENT-SIGNATURE: base64EncodedPaymentSignature

{
  "action": "create_market",
  "coin": "ETH",
  "isBuy": false,
  "dollarSize": 100,
  "reduceOnly": true
}
Testing: Use GET /x402/hyperliquid_order/pricing?dollarSize=1000 to preview the exact fee for any trade size before executing. Payment verification is always required — there is no free testnet mode.
Charts (Paid)
Generate financial chart screenshots with technical indicators for any HyperLiquid asset. No authorization required — just send payment.
chart_screenshot
Render a PNG chart with up to 5 technical indicators. Returns base64-encoded image data.
Request Schema
Field Type Required Description
coinstringYesAsset symbol, e.g. "ETH", "BTC", "SOL"
intervalstringYesCandle interval: "1m", "5m", "15m", "1h", "4h", "1d"
indicatorsstring[]NoTechnical indicators in Name:param format (max 5). See indicator formats below.
daysintegerNoHistory in days (default based on interval)
widthintegerNoImage width 200-1920 (default 1200)
heightintegerNoImage height 200-1080 (default 600)
Indicator Format
Indicators use a Name:param1:param2 syntax. Three forms:
Form Example Description
No paramsMACDUses default parameters
Single paramRSI:14RSI with 14-period lookback
Multi paramBollingerBands:20:2Bollinger Bands, 20-period, 2 std dev
Available Indicators (42 total)
Standard:ADX, ADXFull, Aroon, ATR, BollingerBands, CCI, ChandelierExit, CMF, DEMA, DonchianChannels, EMA, HMA, HorizontalLinesIndicator, Ichimoku, KeltnerChannels, KST, MACD, MFI, MondayRange, OBV, ParabolicSAR, PivotPoints, ROC, RSI, Slope, SMA, StdDev, Stochastic, StochasticRSI, StructuralLevels, SuperTrend, TEMA, TSI, Volume, VWAP, VWMA, WilliamsR, WMA
Pairs (multi-asset, append :ASSET):Beta:ETH, Correlation:ETH, PriceRelativeStrength:ETH, SpreadRatio:ETH
Example Request
curl -X POST https://degenai.dev/x402/chart_screenshot \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: base64EncodedPaymentSignature" \
  -d '{
    "coin": "ETH",
    "interval": "4h",
    "indicators": ["RSI:14", "SMA:200"],
    "width": 1200,
    "height": 600
  }'
Example Response
{
  "success": true,
  "message": "Chart rendered for ETH (4h)",
  "data": {
    "image": "iVBORw0KGgoAAAANSUhEUg...",
    "coin": "ETH",
    "interval": "4h",
    "indicators": ["RSI:14", "SMA:200"],
    "width": 1200,
    "height": 600,
    "contentType": "image/png",
    "timestamp": "2026-03-23T12:00:00.000Z"
  }
}
No authorization needed: Unlike trading, chart requests only require payment — no wallet authorization step. The data.image field contains the full PNG as a base64 string. Decode it to get the raw image bytes.
Rate Limits & Error Codes
Rate Limits
60 requests per minute per IP address. Rate limit headers are included in all responses.
Header Description
X-RateLimit-Limit Maximum requests per window (60)
X-RateLimit-Remaining Requests remaining in current window
X-RateLimit-Reset Unix timestamp when window resets
Error Codes
Code Description Action
PAYMENT_REQUIRED No payment signature provided Add PAYMENT-SIGNATURE header
MISSING_WALLET wallet param missing Include wallet in request body
NOT_AUTHORIZED Trading not authorized Complete /authorize flow first
INSUFFICIENT_BALANCE Not enough USDC/USDM Fund wallet on Base/MegaETH
RATE_LIMITED Too many requests Wait for X-RateLimit-Reset
SIGNATURE_MISMATCH Wrong wallet signed Sign with hyperLiquidWallet
HTTP Status Codes
200 Success | 400 Bad Request | 402 Payment Required | 403 Not Authorized | 429 Rate Limited | 500 Server Error
Error Response Body
All error responses (4xx and 5xx) return the same JSON shape:
{
  "success": false,
  "error": "Human-readable error message",
  "errorCode": "MACHINE_READABLE_CODE",
  "requestId": "trace-id"
}
error (string) and errorCode (string) are always present. requestId is included when available.
402 Payment Required Response
When a paid endpoint is called without a valid PAYMENT-SIGNATURE header, the response includes payment requirements in both the body and a header:
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJzY2hlbWUiOi...  (base64-encoded requirements)

{
  "success": false,
  "error": "Payment required",
  "errorCode": "PAYMENT_REQUIRED",
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "100000",
    "resource": "https://degenai.dev/x402/hyperliquid_order",
    "description": "DegenAI hyperliquid_order execution",
    "mimeType": "application/json",
    "payTo": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 3600
  }
}
The PAYMENT-REQUIRED header contains the same requirements object, base64-encoded. Parse either the header or the body — both contain the same data. maxAmountRequired is in the asset's smallest unit -- USDC uses 6 decimals ("100000" = $0.10), USDM uses 18 decimals.
Payment Signature Payload
The PAYMENT-SIGNATURE header is a base64-encoded JSON object:
{
  "x402Version": 1,
  "scheme": "exact",
  "network": "base",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0xPayerAddress",
      "to": "0xRecipientAddress",
      "value": "100000",
      "validAfter": "0",
      "validBefore": "2147483647",
      "nonce": "0x..."
    }
  }
}
Type notes: value, validAfter, validBefore, and nonce in the authorization block are strings (matching EIP-3009 uint256 encoding). validAfter: "0" (immediately valid) is accepted. The signature is an EIP-3009 TransferWithAuthorization signature over the authorization fields.
Code Examples
import { ethers } from 'ethers';

// 1. Query positions (FREE - no auth needed)
async function getPositions(wallet: string) {
  const response = await fetch('https://degenai.dev/x402/get_positions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ wallet })
  });
  return response.json();
}

// 2. Authorize trading (one-time setup)
async function authorizeTrading(signer: ethers.Signer, payerAddress: string) {
  // Step 1: Prepare
  const prepareRes = await fetch('https://degenai.dev/x402/authorize/prepare', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      payerAddress,
      hyperLiquidWallet: await signer.getAddress()
    })
  });
  const prepareData = await prepareRes.json();
  const { agentApprovalTypedData, builderFeeTypedData, nonce, builderNonce } = prepareData;

  // Step 2: Sign both typed data objects with trading wallet
  const agentApprovalSignature = await signer.signTypedData(
    agentApprovalTypedData.domain,
    agentApprovalTypedData.types,
    agentApprovalTypedData.message
  );
  const builderFeeSignature = builderFeeTypedData
    ? await signer.signTypedData(
        builderFeeTypedData.domain,
        builderFeeTypedData.types,
        builderFeeTypedData.message
      )
    : '';

  // Step 3: Approve
  const approveRes = await fetch('https://degenai.dev/x402/authorize/approve', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      payerAddress,
      hyperLiquidWallet: await signer.getAddress(),
      agentApprovalSignature,
      builderFeeSignature,
      nonce,
      builderNonce
    })
  });
  return approveRes.json();
}

// 3. Execute trade (requires payment signature)
async function executeTrade(paymentSignature: string) {
  const response = await fetch('https://degenai.dev/x402/hyperliquid_order', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'PAYMENT-SIGNATURE': paymentSignature
    },
    body: JSON.stringify({
      action: 'create_market',
      coin: 'ETH',
      isBuy: true,
      dollarSize: 100
    })
  });

  // Handle rate limiting
  if (response.status === 429) {
    const resetTime = response.headers.get('X-RateLimit-Reset');
    console.log(`Rate limited. Retry after: ${resetTime}`);
    throw new Error('Rate limited');
  }

  return response.json();
}
Claude Code Skill
Add DegenAI trading capabilities to Claude Code with a simple skill file.
Slash Commands
/degenai positions <wallet> Query active positions
/degenai account <wallet> Get account summary
/degenai orders <wallet> List open orders
/degenai history <wallet> [limit] Recent trade fills
Natural language also supported: "What are my positions on 0x...?"
Installation
One-liner Install
curl -o .claude/skills/degenai.md https://degenai.dev/skills/degenai-skill.md
Future: Full MCP server for richer integration coming soon.
ERC-8004 Identity
DegenAI is registered on Ethereum mainnet ERC-8004 Identity Registry, enabling on-chain agent discovery and verification.
Agent ID 23121
Contract 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
Chain Ethereum Mainnet
Owner 0xcd1baf2B33781c088B30106289e745972E41b0E8
OpenAgent Market / XMTP
DegenAI is available as a trading agent on OpenAgent Market via XMTP messaging. Other agents can discover and interact with DegenAI by sending JSON-RPC skill requests to our XMTP address.
XMTP Address 0x23a09674e90d04F18Ea307f420a2AeB0d133d8d6
Agent ID (Base) 8453:19162
Protocol JSON-RPC over XMTP
Discovery GET /api/bridge/health
Available Skills
Skill Description Pricing
tradePlace market/limit/stop orders on HyperLiquid$0.10 USDC
authorizeAuthorize your HyperLiquid wallet for tradingFree
authorize_completeComplete authorization (submit signatures)Free
get_assetsList all tradeable assetsFree
get_positionsView open positionsFree
get_ordersView open ordersFree
get_accountAccount summaryFree
get_tradesRecent trade historyFree
get_spot_balancesSpot wallet balancesFree
statusCheck if agent is onlineFree
Example Request
// Send as XMTP message to 0x23a09674e90d04F18Ea307f420a2AeB0d133d8d6
{"method": "get_positions", "params": {"wallet": "0x..."}, "id": 1}