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 { withPaymentInterceptor } from 'x402-axios';
import axios from 'axios';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';

// Create wallet client
const walletClient = createWalletClient({
  account: privateKeyToAccount(PRIVATE_KEY),
  chain: base,
  transport: http('https://mainnet.base.org')
});

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

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
});

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

Portfolio & Analytics

POST /api/search_token

Search for tokens across all blockchains

$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

REQUEST

{
  "wallet_address": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
}

RESPONSE

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

POST /api/analyze_wallet

Wallet behavior and risk analysis

$0.02

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
}

RESPONSE

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

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
}

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"
    }
  ]
}

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
}

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"
}

Airdrop

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/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": "1.0.0"
  },
  "payment": {
    "protocol": "X402",
    "network": "base",
    "recipient": "0x0D224DB2830A32bc75212A0ec6f0008C2B3ae5b5"
  }
}

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

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.

→ 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→ [email protected]