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?
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.
Fee Discount
Automatic 4% HyperLiquid fee reduction on all trades.
IPFS Receipts
Permanent audit trail for every trade stored on IPFS.
FREE Queries
Positions, orders, history - query any wallet at no charge.
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
PAID
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_market | Market order (immediate execution) |
| create_limit | Limit order at a specified price |
| create_stop | Stop/trigger order |
| create_batch | Multiple orders in one request |
| modify_by_oid | Modify an order by HyperLiquid order ID |
| modify_by_cloid | Modify an order by client order ID |
| modify_batch | Modify multiple orders |
| cancel_by_oid | Cancel by HyperLiquid order ID |
| cancel_by_cloid | Cancel by client order ID |
| cancel_batch | Cancel multiple orders |
Request Schema — Market Order
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | "create_market" |
| coin | string | Yes | Asset symbol, e.g. "ETH", "BTC" |
| isBuy | boolean | Yes | true = long, false = short |
| dollarSize | number | Yes | Order size in USD (min 1) |
| reduceOnly | boolean | No | Only reduce existing position (default: false) |
| takeProfitPrice | number | No | Attach take-profit at this price |
| stopLossPrice | number | No | Attach stop-loss at this price |
| cloid | string | No | Client order ID (0x + 32 hex chars) |
Request Schema — Limit Order
Same fields as market, plus:
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | "create_limit" |
| price | number | Yes | Limit price (must be > 0) |
| tif | string | No | Time-in-force: "Gtc" (default), "Ioc", "Alo" |
Request Schema — Cancel Order
| Field | Type | Required | Description |
|---|---|---|---|
| action | string | Yes | "cancel_by_oid" or "cancel_by_cloid" |
| coin | string | Yes | Asset symbol |
| oid | integer | Cond. | HyperLiquid order ID (for cancel_by_oid) |
| cloid | string | Cond. | 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
4. Response includes IPFS receipt CID for verification
2. Base64 encode the payment payload
3. Include as
PAYMENT-SIGNATURE header4. 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
$0.005
Render a PNG chart with up to 5 technical indicators. Returns base64-encoded image data.
Request Schema
| Field | Type | Required | Description |
|---|---|---|---|
| coin | string | Yes | Asset symbol, e.g. "ETH", "BTC", "SOL" |
| interval | string | Yes | Candle interval: "1m", "5m", "15m", "1h", "4h", "1d" |
| indicators | string[] | No | Technical indicators in Name:param format (max 5). See indicator formats below. |
| days | integer | No | History in days (default based on interval) |
| width | integer | No | Image width 200-1920 (default 1200) |
| height | integer | No | Image height 200-1080 (default 600) |
Indicator Format
Indicators use a
Name:param1:param2 syntax. Three forms:
| Form | Example | Description |
|---|---|---|
| No params | MACD | Uses default parameters |
| Single param | RSI:14 | RSI with 14-period lookback |
| Multi param | BollingerBands:20:2 | Bollinger 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, WMAPairs (multi-asset, append :ASSET):
Beta:ETH, Correlation:ETH, PriceRelativeStrength:ETH, SpreadRatio:ETHExample 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
Future: Full MCP server for richer integration coming soon.
ERC-8004 Identity
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 |
|---|---|---|
| trade | Place market/limit/stop orders on HyperLiquid | $0.10 USDC |
| authorize | Authorize your HyperLiquid wallet for trading | Free |
| authorize_complete | Complete authorization (submit signatures) | Free |
| get_assets | List all tradeable assets | Free |
| get_positions | View open positions | Free |
| get_orders | View open orders | Free |
| get_account | Account summary | Free |
| get_trades | Recent trade history | Free |
| get_spot_balances | Spot wallet balances | Free |
| status | Check if agent is online | Free |
Example Request
// Send as XMTP message to 0x23a09674e90d04F18Ea307f420a2AeB0d133d8d6
{"method": "get_positions", "params": {"wallet": "0x..."}, "id": 1}
