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

Call execute endpoint → receive pipeline_id
Monitor status with /api/get_transaction_status
When status is "sign_pending", sign the tx_data
Submit signed transaction to blockchain
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);
}

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

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": [
    {
      "type": "approval",
      "status": "success",
      "tx_hash": "0xabc..."
    },
    {
      "type": "swap",
      "status": "sign_pending",
      "tx_data": {...}
    }
  ]
}

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