ELSA LogoELSA | X402
VERSION 1.0.0 • REAL BLOCKCHAIN EXECUTION

Complete API Documentation

Execute real blockchain transactions through the Elsa pipeline system. Pay-per-use with X402 micropayments on Base network.

HTTP REST APIPIPELINE SYSTEMX402 PAYMENTS

Quick Start

1. SETUP X402 CLIENT

import { wrapAxiosWithPayment, x402Client } from '@x402/axios';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';
import axios from 'axios';

// x402 v2 client: register the EVM 'exact' scheme on Base (CAIP-2 eip155:8453)
const account = privateKeyToAccount(PRIVATE_KEY);

// walletClient signs/sends the swap transaction in later steps
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http('https://mainnet.base.org')
});

const paymentClient = new x402Client().register(
  'eip155:8453',
  new ExactEvmScheme(account, { rpcUrl: 'https://mainnet.base.org' })
);

// Apply the X402 v2 payment interceptor
const client = wrapAxiosWithPayment(
  axios.create({ baseURL: 'https://x402-v2-api.heyelsa.ai' }),
  paymentClient
);

2. MAKE API CALLS

// Get portfolio (costs $0.01)
const portfolio = await client.post('/api/get_portfolio', {
  wallet_address: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7'
});

// Execute swap (costs $0.02)
const swap = await client.post('/api/execute_swap', {
  from_chain: 'base',
  from_token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  from_amount: '100',
  to_chain: 'base',
  to_token: '0x4200000000000000000000000000000000000006',   // WETH
  wallet_address: '0x...',
  slippage: 2.0,
  dry_run: false  // Real execution
});

💡 PAYMENT TOKEN SELECTION

Pay with USDC (default):
https://x402-v2-api.heyelsa.ai/api/endpoint_name
Pay with ELSA token:
https://x402-v2-api.heyelsa.ai/api/elsa/endpoint_name

Both paths support the same endpoints with identical functionality. The only difference is the payment token used for X402 micropayments on Base network.

ELSA prices are derived from a live ELSA/USD feed. If that feed is unavailable, /api/elsa/* answers 503 while the USDC path keeps working — fall back to /api/endpoint_name. The server re-checks the price every 5 minutes and re-enables ELSA automatically.GET /health reports the current state in pricing.elsaPaymentsAvailable.

X402 Protocol Headers

This API speaks x402 v2. Payment requirements, the signed payment and the settlement receipt all travel in Base64-encoded JSON headers: PAYMENT-REQUIRED on the 402, PAYMENT-SIGNATURE on the paid request, and PAYMENT-RESPONSE on the 200. The 402 body is an empty {} — read the header, not the body. The @x402/axios client in the quick start handles all of this for you; the details below are for hand-rolled clients.

REQUEST / RESPONSE FLOW

  1. Client makes a request to a protected endpoint — no PAYMENT-SIGNATURE header
  2. Server replies 402 Payment Required with an empty JSON body and a PAYMENT-REQUIRED header listing the accepts options
  3. Client picks one option, signs an EIP-3009 authorization for its amount, and retries with the PAYMENT-SIGNATURE request header
  4. Server verifies, runs the handler, settles on-chain, and replies 200 OK with the PAYMENT-RESPONSE header

PAYMENT-REQUIRED

SERVER → CLIENTRESPONSE HEADER · 402

Returned when no valid payment is provided. The body is {}; the header is a Base64-encoded PaymentRequired JSON object listing the options the client must satisfy under accepts. Browsers can read it — it is on the CORS Access-Control-Expose-Headers list.

EXAMPLE RESPONSE

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIiwicmVzb3VyY2UiOnsidXJsIjo...

{}

DECODED HEADER

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://x402-v2-api.heyelsa.ai/api/get_portfolio",
    "description": "",
    "mimeType": ""
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0xEcB6175395806A3781AE7E5bae6d0abcB214Ee4D",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "extensions": { "builder-code": { ... } }
}
x402Version — protocol version (2)
resource.url — the endpoint being paid for
accepts[].amount — cost in token base units (10000 = $0.01 USDC at 6 decimals)
accepts[].asset — ERC-20 contract address for the payment token
accepts[].payTo — recipient wallet address
accepts[].network — CAIP-2 chain id (eip155:8453 = Base mainnet)
accepts[].maxTimeoutSeconds — validity window for the signed authorization
accepts[].extra — EIP-712 domain fields (name, version) for the asset
extensions — optional protocol extensions (builder-code attribution); clients may ignore them

PAYMENT-SIGNATURE

CLIENT → SERVERREQUEST HEADER

Sent by the client on the retry request. Value is a Base64-encoded PaymentPayload JSON object: the accepts entry you chose, echoed back as accepted, plus a signed EIP-3009 transferWithAuthorization for that entry's amount to its payTo.

EXAMPLE REQUEST HEADERS

POST /api/get_portfolio HTTP/1.1
Content-Type: application/json
PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0ZWQiOnsic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLC...

DECODED VALUE

{
  "x402Version": 2,
  "resource": { "url": "https://x402-v2-api.heyelsa.ai/api/get_portfolio" },
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xEcB6175395806A3781AE7E5bae6d0abcB214Ee4D",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  },
  "payload": {
    "signature": "0x2d6a7588d6acca505cbf0d9a4a227e0c52c6c340...1c",
    "authorization": {
      "from": "0x857b06519E91e3A54538791bDbb0E22373e36b66",
      "to": "0xEcB6175395806A3781AE7E5bae6d0abcB214Ee4D",
      "value": "10000",
      "validAfter": "0",
      "validBefore": "1740672154",
      "nonce": "0xf3746613c2d920b5fdabc0856f2aeb2d4f88ee60..."
    }
  }
}
accepted — one of the accepts options, copied verbatim
payload.signature — EIP-712 signature over the authorization, using the asset's domain from extra
authorization.from — payer wallet address
authorization.to / value — must equal accepted.payTo and accepted.amount
authorization.validAfter/Before — Unix timestamps bounding validity (validBefore ≤ now + maxTimeoutSeconds)
authorization.nonce — random bytes32 to prevent replay

PAYMENT-RESPONSE

SERVER → CLIENTRESPONSE HEADER · 200

Returned alongside the 200 OK response after successful settlement. Provides the on-chain transaction hash for auditing. Value is a Base64-encoded SettleResponse JSON object. The same value is mirrored in the legacy X-PAYMENT-RESPONSE header for v1-era clients.

EXAMPLE RESPONSE HEADERS

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4MTIzNDU2NzgiLCJuZXR3b3JrIjoi...

DECODED VALUE

{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:8453",
  "payer": "0x857b06519E91e3A54538791bDbb0E22373e36b66"
}
success — whether settlement completed
transaction — on-chain tx hash (verifiable on BaseScan)
network — CAIP-2 chain id (eip155:8453 = Base mainnet)
payer — wallet address that paid
errorReason / errorMessage — present only when success is false

HTTP STATUS CODES

200OKPayment verified & settled — resource returned with the PAYMENT-RESPONSE header
402Payment RequiredMissing PAYMENT-SIGNATURE header, malformed or invalid payment, facilitator verification failed, or on-chain settlement rejected — the PAYMENT-REQUIRED header carries x402Version, error, and the accepts options; the body is {}
400Bad RequestRequest body failed schema validation — a required endpoint parameter is missing or wrong-typed
503Service UnavailableELSA path only (/api/elsa/*) — the ELSA/USD price feed is down so ELSA payments are paused. Use the USDC path (/api/<endpoint>); ELSA routes re-enable automatically once pricing recovers (re-checked every 5 minutes)
500Server ErrorUnexpected internal server error unrelated to payment processing

Pipeline Transaction System

All execute endpoints use the Elsa pipeline for transaction orchestration. The pipeline handles approvals, swaps, and monitoring.

PIPELINE FLOW

  1. Call execute endpoint → receive pipeline_id
  2. Monitor status with /api/get_transaction_status
  3. When status is "sign_pending", sign the tx_data
  4. Submit signed transaction to blockchain
  5. Submit transaction hash to pipeline via /api/submit_transaction_hash
  6. Continue monitoring until "success" status

REAL SWAP EXAMPLE

// 1. Execute swap
const result = await client.post('/api/execute_swap', {
  from_chain: 'base',
  from_token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
  from_amount: '100',
  to_chain: 'base',
  to_token: '0x4200000000000000000000000000000000000006',   // WETH
  wallet_address: '0x...',
  slippage: 2.0,
  dry_run: false  // Real execution
});

// 2. Monitor pipeline
const status = await client.post('/api/get_transaction_status', {
  pipeline_id: result.data.result.pipeline_id
});

// 3. Sign when ready
if (status.data.status[0].status === 'sign_pending') {
  const hash = await walletClient.sendTransaction(status.data.status[0].tx_data);

  // 4. Submit transaction hash back to pipeline
  await client.post('/api/submit_transaction_hash', {
    task_id: status.data.status[0].task_id,
    tx_hash: hash,
    status: 'submitted'
  });
}

API Endpoints

BASE URL

Pay with USDC:
https://x402-v2-api.heyelsa.ai/api/
Pay with ELSA token:
https://x402-v2-api.heyelsa.ai/api/elsa/

All endpoints listed below work with both base URLs. Simply change the path prefix to switch payment tokens. The ELSA path returns 503 while ELSA pricing is unavailable; the USDC path is unaffected.

Portfolio & Analytics

POST /api/search_token

Search for tokens across all blockchains

or /api/elsa/search_token

$0.001

REQUEST

{
  "symbol_or_address": "USDC",
  "limit": 5
}

RESPONSE

{
  "success": true,
  "result": {
    "results": [
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "chain": "base",
        "priceUSD": "1.000"
      }
    ]
  }
}

POST /api/get_token_price

Get real-time token price

$0.002

REQUEST

{
  "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "chain": "base"
}

POST /api/get_balances

Get wallet token balances

$0.005

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

RESPONSE

{
  "balances": [
    {
      "asset": "USDC",
      "balance": "1250.50",
      "balance_usd": "1250.50",
      "chain": "base"
    }
  ]
}

POST /api/get_portfolio

Comprehensive portfolio analysis

$0.01

DESCRIPTION

Get a comprehensive view of wallet holdings including balances, DeFi positions, staking positions, and perpetual trading positions across Avantis and Hyperliquid.

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

RESPONSE

{
  "wallet_address": "0x0D224DB...",
  "total_value_usd": "12345.67",
  "chains": ["ethereum", "base", "arbitrum"],
  "portfolio": {
    "balances": [...],
    "defi_positions": [...],
    "staking_positions": [...],
    "perpetual_positions": {
      "avantis": [...],
      "hyperliquid": [...]
    }
  }
}

POST /api/analyze_wallet

Wallet behavior and risk analysis

$0.02

DESCRIPTION

Analyze wallet activity, behavior patterns, and risk profile including perpetual trading positions across Avantis and Hyperliquid.

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

POST /api/get_pnl_report

Profit and loss analysis

$0.015

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "time_period": "30_days"
}

Trading

POST /api/get_swap_quote

Get optimal swap routing and pricing

$0.01

REQUEST

{
  "from_chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",  // USDC
  "from_amount": "100",
  "to_chain": "base",
  "to_token": "0x4200000000000000000000000000000000000006",      // WETH
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "slippage": 2.0,
  "provider": "cowswap",       // optional — force a specific route
  "gasless_only": true,        // optional — signature-settled routes only
  "to_address": "0xYourPolymarketDepositWallet"  // optional — defaults to wallet_address; see parameter notes
}

RESPONSE

{
  "quote": {
    "from_amount": "100",
    "estimatedOutput": "0.0283",
    "price_impact": "0.12",
    "gas_estimate": "0.45",
    "route": ["USDC", "WETH"]
  }
}

PARAMETERS

Accepts the same optional routing parameters as execute_swap — provider, gasless_only and to_address — so a quote reflects the route that will actually be executed. See the parameter table below.

POST /api/execute_swap

Execute real blockchain swap

$0.02

REQUEST

{
  "from_chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_amount": "100",
  "to_chain": "base",
  "to_token": "0x4200000000000000000000000000000000000006",
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "slippage": 2.0,
  "dry_run": false,
  "provider": "cowswap",       // optional — force a specific route
  "gasless_only": true,        // optional — signature-settled routes only
  "to_address": "0xYourPolymarketDepositWallet"  // optional — defaults to wallet_address; see parameter notes
}

RESPONSE (Pipeline Created)

{
  "pipeline_id": "pip_123456789",
  "tasks": [
    {
      "type": "approval",
      "status": "sign_pending",
      "tx_data": {
        "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "data": "0x095ea7b3...",
        "value": "0x0"
      }
    },
    {
      "type": "swap",
      "status": "pending"
    }
  ]
}

PARAMETERS

slippage (number, optional) - Max slippage in percent, 0–50 (default: 0.5)
dry_run (boolean, optional) - Defaults to true. Returns the route and estimate without creating a pipeline; set false to execute.
provider (string, optional) - Force a specific swap route. Omit to let the router pick the best route. The backend rejects a provider that cannot serve the requested pair or chains. Accepted values:
lifibungeerelayrialtofyndsuperswapberachainhyperliquidhyperliquid-perpscowswapagent_token_lp
cowswap is the signature-settled (gasless) same-chain route; relay in permit mode is the gasless bridge route for EIP-3009 tokens such as USDC.
gasless_only (boolean, optional) - Only route through providers that settle by signature (CoW Swap for same-chain swaps; Relay permit mode for bridges of EIP-3009 tokens such as USDC), so a wallet holding no ETH can still trade. The request fails instead of falling back to a route that needs gas.
to_address (string, optional) - Recipient on the destination chain. Defaults to wallet_address. On same-chain and EVM-to-EVM routes it must equal wallet_address, with one exception: your own Polymarket V2 deposit wallet when to_token is pUSD on Polygon, so a bridge can land where Polymarket trades from. Anything else is rejected with a 400.

POST /api/create_limit_order

Create limit order via CoW Protocol

$0.05

REQUEST

{
  "from_chain": "ethereum",
  "from_token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "from_amount": "1000",
  "to_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
  "limit_price": "0.0003",
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "valid_for_hours": 24,
  "dry_run": false
}

POST /api/get_limit_orders

View limit orders

$0.002

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

POST /api/cancel_limit_order

Cancel pending limit order

$0.01

REQUEST

{
  "order_id": "0x123...",
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "dry_run": false
}

Perpetual Trading

POST /api/get_available_perp_pairs

List available perpetual trading pairs

$0.001

DESCRIPTION

Get a list of available perpetual trading pairs across providers. Supports Avantis (Base, Arbitrum) and Hyperliquid.

REQUEST

{
  "provider": "all"
}

PARAMETERS

provider (string, optional) - "avantis", "hyperliquid", or "all" (default: "all")

PROVIDERS

avantis
Avantis
hyperliquid
Hyperliquid

Use all to query across all providers simultaneously.

RESPONSE

{
  "success": true,
  "pairs": {
    "avantis": [
      {
        "pair": "ETH-USD",
        "chain": "base",
        "max_leverage": 50
      }
    ],
    "hyperliquid": [
      {
        "pair": "BTC-USD",
        "max_leverage": 50
      }
    ]
  }
}

POST /api/get_perp_positions

Query perpetual trading positions

$0.002

DESCRIPTION

Get all open perpetual positions for a wallet across Avantis and Hyperliquid providers.

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "provider": "all"
}

PARAMETERS

wallet_address (string, required) - Wallet address to check
provider (string, optional) - "avantis", "hyperliquid", or "all" (default: "all")

RESPONSE

{
  "success": true,
  "positions": {
    "avantis": [
      {
        "pair": "ETH-USD",
        "size": "1.5",
        "side": "long",
        "leverage": 10,
        "entry_price": "2500.00",
        "pnl": "150.00"
      }
    ],
    "hyperliquid": []
  }
}

POST /api/get_perp_details

Get Hyperliquid market details for a specific token

$0.002

DESCRIPTION

Get detailed market information for a specific perpetual contract on Hyperliquid, including funding rates and open interest.

REQUEST

{
  "token": "ETH"
}

PARAMETERS

token (string, required) - Token symbol (e.g., "ETH", "BTC")

RESPONSE

{
  "success": true,
  "details": {
    "token": "ETH",
    "mark_price": "2500.00",
    "funding_rate": "0.0001",
    "open_interest": "1000000",
    "max_leverage": 50
  }
}

POST /api/open_perp_position

Open a new perpetual position

$0.05

DESCRIPTION

Open a new long or short perpetual position on Avantis (Base, Arbitrum) or Hyperliquid. Supports stop loss and take profit parameters. User confirmation required for non-dry-run executions.

REQUEST

{
  "provider": "avantis",
  "chain": "base",
  "pair": "ETH-USD",
  "collateral_token": "USDC",
  "collateral_amount": "1000",
  "leverage": 10,
  "side": "long",
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "stop_loss": "2400",
  "take_profit": "2600",
  "dry_run": false
}

PARAMETERS

provider (string, required) - "avantis" or "hyperliquid"
chain (string, required for Avantis) - "base" or "arbitrum"
pair (string, required) - Trading pair (e.g., "ETH-USD")
collateral_token (string, required) - Collateral token symbol
collateral_amount (string, required) - Amount of collateral
leverage (number, required) - Leverage multiplier (max 50x for Hyperliquid)
side (string, required) - "long" or "short"
wallet_address (string, required) - Wallet address
stop_loss (string, optional) - Stop loss price
take_profit (string, optional) - Take profit price
dry_run (boolean, optional) - Test mode (default: false)

RESPONSE (Pipeline Created)

{
  "success": true,
  "pipeline_id": "pip_perp_123456",
  "tasks": [
    {
      "task_id": "task_abc123",
      "action_type": "perp_open",
      "status": "sign_pending",
      "tx_data": {
        "to": "0x...",
        "data": "0x...",
        "value": "0x0"
      }
    }
  ]
}

POST /api/close_perp_position

Close a perpetual position

$0.05

DESCRIPTION

Close a perpetual position fully or partially (1-100%). Supports both Avantis and Hyperliquid providers.

REQUEST

{
  "provider": "avantis",
  "chain": "base",
  "pair": "ETH-USD",
  "position_id": "pos_123",
  "close_percentage": 100,
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "dry_run": false
}

PARAMETERS

provider (string, required) - "avantis" or "hyperliquid"
chain (string, required for Avantis) - "base" or "arbitrum"
pair (string, required) - Trading pair
position_id (string, required) - Position identifier
close_percentage (number, required) - Percentage to close (1-100)
wallet_address (string, required) - Wallet address
dry_run (boolean, optional) - Test mode (default: false)

RESPONSE (Pipeline Created)

{
  "success": true,
  "pipeline_id": "pip_perp_close_123",
  "tasks": [
    {
      "task_id": "task_def456",
      "action_type": "perp_close",
      "status": "sign_pending",
      "tx_data": {...}
    }
  ]
}

Prediction Markets

POST /api/polymarket_search_markets

Search Polymarket prediction markets by keyword

or /api/elsa/polymarket_search_markets

$0.002

REQUEST

{
  "search": "bitcoin"
}

RESPONSE

{
  "markets": [
    {
      "id": "0x1234...",
      "question": "Will Bitcoin exceed $100k by end of 2025?",
      "outcomes": ["Yes", "No"],
      "prices": [0.62, 0.38],
      "volume": "1250000",
      "end_date": "2025-12-31"
    }
  ]
}

POST /api/polymarket_user_status

Get Polymarket account status, deposit wallet, balances, and allowances

or /api/elsa/polymarket_user_status

$0.002

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

POST /api/polymarket_user_data

Get user positions, trades, and open orders

or /api/elsa/polymarket_user_data

$0.005

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "include_open_positions": true,
  "include_won_positions": true,
  "include_orders": false,  // requires encrypted_credentials
  "include_trades": false,
  "encrypted_credentials": "..."  // optional, only needed for include_orders
}

POST /api/polymarket_advanced_search

Screen Polymarket markets by date range, probability band, spread and sort order

or /api/elsa/polymarket_advanced_search

$0.002

REQUEST

{
  "search": "election",                      // optional — omit to screen ALL markets
  "limit": 20,                               // optional, max 50
  "sort_by": "volumeUsd24h",                 // optional, default trendingScore24h
  "sort_direction": "DESC",                  // optional, ASC | DESC
  "start_date_min": "2026-01-01T00:00:00Z",  // optional ISO 8601
  "start_date_max": "2026-12-31T23:59:59Z",  // optional
  "end_date_min": "2026-06-01T00:00:00Z",    // optional
  "end_date_max": "2027-01-01T00:00:00Z",    // optional
  "price_competitiveness_min": 0.30,         // optional, 0–1
  "price_competitiveness_max": 0.40,         // optional, 0–1
  "spread_min": 0,                           // optional, USD per share
  "spread_max": 0.005                        // optional, USD per share
}

PARAMETERS

search (string, optional, max 200 chars) - Keyword resolved to a single Polymarket tag. Omit it to screen across all markets — a keyword narrows the universe to one topic, so only pass one when you actually want that topic.
sort_by (string, optional) - One of trendingScore24h (default), volumeUsd24h, openInterestUsd, liquidityUsd, competitiveScore24h, uniqueTraders24h, trades24h
sort_direction (string, optional) - "ASC" or "DESC" (default)
start_date_min / start_date_max / end_date_min / end_date_max (string, optional) - ISO 8601 timestamps bounding the market start and end dates
price_competitiveness_min / price_competitiveness_max (number, optional, 0–1) - Bounds on priceCompetitiveness = 1 − |p_yes − p_no|, a leg-agnostic probability band. 0.30–0.40 ≈ a favorite priced at 80–85% on either side; 0 = fully decided, 1 = coin flip.
spread_min / spread_max (number, optional, 0–1) - Bounds on the per-outcome bid-ask spread in USD per share, applied to both legs. spread_max 0.005 selects tight books.

POST /api/create_polymarket_v2_order

Create a Polymarket order via pipeline — no credential setup required

or /api/elsa/create_polymarket_v2_order

$0.05

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",  // your EOA
  "market_id": "0x1234...",
  "token_id": "123456789",  // outcome token (Yes/No)
  "side": "buy",             // "buy" | "sell"
  "price": 0.62,             // price per share in USDC, 0.0–1.0
  "size": 100,               // order size in USD (minimum 1)
  "neg_risk": true,          // optional, backend overrides from the live order book
  "dry_run": false           // optional, defaults to true (preview only)
}

RESPONSE (Pipeline Created)

{
  "pipeline_id": "pip_abc123",
  "tasks": [ ... ]  // monitor via get_transaction_status
}

PARAMETERS

wallet_address (string, required) - Your EOA (0x...). The Polymarket deposit wallet is derived server-side — deployed and approved automatically on first order.
side (string, required) - "buy" or "sell" (lowercase)
price (number, required) - Price per share in USDC, 0.0–1.0 (e.g. 0.65 = 65 cents)
size (number, required) - Order size in USD, minimum 1
neg_risk (boolean, optional) - Defaults to true; the backend overrides this from the live order book
dry_run (boolean, optional) - Defaults to true. Returns a quote without placing the order; set false to execute.

DESCRIPTION

No credential setup step is required — CLOB credentials are derived automatically, and the deposit wallet is deployed and approved on demand. Fund the deposit wallet with pUSD before placing buy orders; underfunded buys are rejected.

Staking & Yield

POST /api/get_stake_balances

View staking positions

$0.005

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

RESPONSE

{
  "total_staked_usd": "15250.75",
  "stakes": [
    {
      "protocol": "Lido",
      "token": "ETH",
      "staked_amount": "5.0",
      "apy": "4.2"
    }
  ]
}

POST /api/get_yield_suggestions

Discover yield opportunities

$0.02

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

POST /api/get_yield_portfolio

Get active yield farming positions for a wallet

$0.02

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "chains": ["ethereum", "arbitrum"],
  "min_apy": 5,
  "max_risk": "medium",
  "yield_types": ["staking", "lending"]
}

PARAMETERS

wallet_address (string, required) - EVM (0x...) or Solana address
tokens (string[], optional) - Filter by token symbols
chains (string[], optional) - Filter by chains (e.g., "ethereum", "arbitrum")
min_apy (number, optional) - Minimum APY percentage
max_risk (string, optional) - "low" | "medium" | "high"
yield_types (string[], optional) - "staking" | "liquid-staking" | "vault" | "lending" | "farming" | "liquid-restaking"
yield_ids (string[], optional) - Specific yield IDs to check

Airdrop

SEASON 1 ENDED

Airdrop Season 1 has ended. The endpoints below remain available for historical claim checks and any pending/unclaimed allocations from Season 1. Watch for Season 2 announcements.

POST /api/check_airdrop

Check airdrop eligibility and allocation

$0.002

REQUEST

{
  "chain": "base",
  "tranche": 1,
  "eoa_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

PARAMETERS

chain (string, required) - Blockchain network for the airdrop
tranche (number, required) - Airdrop tranche number (minimum: 1)
eoa_address (string, required) - Ethereum wallet address for airdrop check

RESPONSE

{
  "success": true,
  "chain": "base",
  "tranche": 1,
  "eoa_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "airdrop_info": {
    "chain": "base",
    "from_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
    "amount": 1000.0,
    "tranche": 1,
    "status": "available"
  },
  "timestamp": "2025-01-19T12:00:00.000Z"
}

airdrop_info.status values:

  • available - Eligible to claim
  • claimed - Already claimed

POST /api/claim_airdrop

Claim ELSA airdrop tokens

$0.001

DESCRIPTION

Creates a pipeline to claim your allocated ELSA tokens from a specific tranche. Use dry_run to preview the claim without executing. Once the pipeline is created, monitor with get_transaction_status and sign the transaction when status is "sign_pending".

REQUEST

{
  "chain": "base",
  "tranche": 1,
  "eoa_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "dry_run": false
}

PARAMETERS

chain (string, required) - Blockchain network for the airdrop
tranche (number, required) - Airdrop tranche number (minimum: 1)
eoa_address (string, required) - Ethereum wallet address for airdrop claim
dry_run (boolean, optional) - Preview claim without executing (default: false)

RESPONSE (Pipeline Created)

{
  "success": true,
  "pipeline_id": "pip_abc123def456",
  "chain": "base",
  "tranche": 1,
  "eoa_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "result": {
    "pipeline_id": "pip_abc123def456",
    "tasks": [
      {
        "task_id": "task_xyz789",
        "action_type": "claim_elsa_airdrop",
        "status": "sign_pending",
        "tx_data": {
          "to": "0x...",
          "data": "0x...",
          "value": "0x0"
        }
      }
    ]
  },
  "timestamp": "2025-01-19T12:00:00.000Z"
}

The response includes a pipeline_id and result object containing tasks. Use the pipeline_id with /api/get_transaction_status to monitor progress and get tx_data for signing.

Transaction Management

POST /api/get_transaction_history

Get transaction history

$0.003

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
  "limit": 10
}

POST /api/get_transaction_status

Monitor pipeline status

$0.001

REQUEST

{
  "pipeline_id": "pip_123456789"
}

RESPONSE

{
  "pipeline_id": "pip_123456789",
  "status": "in_progress",
  "tasks": [
    {
      "task_id": "task_abc123",
      "type": "approval",
      "status": "success",
      "tx_hash": "0xabc..."
    },
    {
      "task_id": "task_def456",
      "type": "swap",
      "status": "sign_pending",
      "tx_data": {...}
    }
  ]
}

POST /api/submit_transaction_hash

Submit signed transaction hash to pipeline

$0.005

DESCRIPTION

After signing a transaction with your wallet, submit the transaction hash back to the pipeline. This is required for multi-task pipelines (e.g., approval + swap) to track transaction status and continue with subsequent tasks.

REQUEST

{
  "task_id": "task_def456",
  "tx_hash": "0x1234567890abcdef...",
  "status": "submitted"
}

PARAMETERS

task_id (string, required) - Task ID from get_transaction_status
tx_hash (string, required) - Signed transaction hash from RPC
status (string, required) - Either "submitted" or "rejected"
error (string, optional) - Error message if status is "rejected"

RESPONSE

{
  "success": true,
  "task_id": "task_def456",
  "tx_hash": "0x1234567890abcdef...",
  "status": "submitted"
}

POST /api/submit_typed_data_signature

Submit EIP-712 typed data signature to pipeline

$0.005

DESCRIPTION

After signing an EIP-712 typed data payload with your wallet, submit the signature back to the pipeline. Used by flows that require off-chain signatures (e.g., Polymarket order authorization, limit orders) to continue with subsequent tasks.

REQUEST

{
  "task_id": "task_def456",
  "signature": "0xabcdef1234...",
  "status": "signed"
}

PARAMETERS

task_id (string, required) - Task ID from get_transaction_status
signature (string, required when status is "signed") - EIP-712 signature returned by the wallet
status (string, optional) - "signed" (default) or "rejected"
error (string, optional) - Error message if status is "rejected"

RESPONSE

{
  "success": true,
  "task_id": "task_def456",
  "signature": "0xabcdef1234...",
  "status": "signed"
}

POST /api/get_gas_prices

Current gas prices

$0.001

REQUEST

{
  "chain": "base"
}

Free Endpoints

GET /health

Server health check

FREE

RESPONSE

{
  "status": "healthy",
  "service": {
    "name": "Elsa X402 MCP Server",
    "version": "2.0.0"
  },
  "payment": {
    "protocol": "X402",
    "network": "base",
    "recipient": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
  },
  "pricing": {
    "currentElsaPrice": 0.05,
    "elsaPaymentsAvailable": true,   // false => /api/elsa/* returns 503
    "lastUpdate": "2026-10-09T12:00:00.000Z"
  }
}

DESCRIPTION

pricing.elsaPaymentsAvailable tells you whether the ELSA payment path is live. It flips to false when the ELSA/USD price feed cannot be reached; USDC endpoints keep working, and the server retries the feed every 5 minutes.

MCP Integration

COMING SOON

MCP integration will be available shortly

CLAUDE DESKTOP CONFIGURATION

{
  "mcpServers": {
    "elsa-x402": {
      "command": "node",
      "args": ["/path/to/elsa-x402-mcp-server/build/index.js"],
      "env": {
        "X402_NETWORK": "base",
        "X402_PAY_TO": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5",
        "CDP_API_KEY_ID": "your-cdp-key-id",
        "CDP_API_KEY_SECRET": "your-cdp-key-secret"
      }
    }
  }
}

AVAILABLE MCP TOOLS

search_token
get_token_price
get_portfolio
get_balances
analyze_wallet
get_pnl_report
get_swap_quote
execute_swap
create_limit_order
get_limit_orders
cancel_limit_order
get_stake_balances
open_perp_position
close_perp_position
get_perp_positions
get_available_perp_pairs
get_perp_details

References & Resources

Learn more about the X402 protocol and related technologies powering this API.

X402 PROTOCOL

The HTTP 402 Payment Required protocol enabling machine-to-machine micropayments.

→ x402.org (Official Site)→ GitHub: coinbase/x402

COINBASE DEVELOPER PLATFORM

CDP provides the wallet infrastructure for X402 payment processing.

→ CDP Documentation→ CDP Portal

BASE NETWORK

The L2 blockchain where X402 payments are processed in USDC or ELSA.

→ base.org→ Base Documentation→ BaseScan Explorer

MCP PROTOCOL

Model Context Protocol for AI assistant integrations.

→ modelcontextprotocol.io→ GitHub: modelcontextprotocol

Need Help?

For issues or questions, reach out through our support channels

→ Examples Repository→ llms-full.txt (for AI agents)→ [email protected]