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 | Token Address |
|---|---|---|---|
| Base | 8453 | USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| MegaETH | 4326 | USDM | 0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7 |
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.
1
Prepare Authorization
POST /x402/authorize/prepare
Content-Type: application/json
{
"payerAddress": "0xYourPayerWallet",
"hyperLiquidWallet": "0xYourTradingWallet"
}
Returns EIP-712 typed data for signing:
agentApprovalTypedData2
Sign the Typed Data
// Sign with your HyperLiquid trading wallet
const signature = await wallet.signTypedData(
agentApprovalTypedData.domain,
agentApprovalTypedData.types,
agentApprovalTypedData.message
);
3
Approve Authorization
POST /x402/authorize/approve
Content-Type: application/json
{
"payerAddress": "0xYourPayerWallet",
"hyperLiquidWallet": "0xYourTradingWallet",
"signature": "0xYourSignature...",
"nonce": 1234567890
}
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
Pricing
$0.10
+
0.01%
of trade size
Example: $1,000 trade = $0.10 + $0.10 = $0.20 total
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
POST /x402/hyperliquid_order
Content-Type: application/json
PAYMENT-SIGNATURE: base64EncodedPaymentSignature
{
"wallet": "0xYourTradingWallet",
"coin": "ETH",
"side": "buy",
"dollarSize": 100,
"orderType": "market"
}
Example Response
{
"success": true,
"message": "Order executed successfully",
"data": {
"orderId": "0x123...",
"coin": "ETH",
"side": "buy",
"size": "0.04",
"avgPrice": "2500.00",
"status": "filled",
"ipfsReceipt": "QmXyz..."
},
"requestId": "req_abc123",
"executedAt": "2026-02-10T12:00:00Z"
}Testing Mode: Use HyperLiquid testnet by adding
"testnet": true to request body.
No real funds required for testing. Same API, different HyperLiquid environment.
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
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 { agentApprovalTypedData, nonce } = await prepareRes.json();
// Step 2: Sign the typed data
const signature = await signer.signTypedData(
agentApprovalTypedData.domain,
agentApprovalTypedData.types,
agentApprovalTypedData.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(),
signature,
nonce
})
});
return approveRes.json();
}
// 3. Execute trade (requires payment signature)
async function executeTrade(paymentSignature: string, wallet: string) {
const response = await fetch('https://degenai.dev/x402/hyperliquid_order', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'PAYMENT-SIGNATURE': paymentSignature
},
body: JSON.stringify({
wallet,
coin: 'ETH',
side: 'buy',
dollarSize: 100,
orderType: 'market'
})
});
// 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

