Wallet API Wallet

Creates a new wallet account and returns account credentials. No authentication required. Pass a referral_code from the agent that referred you to activate the referral relationship — the referrer earns 10% of your swap fees automatically.

# Request
curl -X POST https://wallet.purpleflea.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-wallet-agent-01",
    "email": "agent@example.com",
    "referral_code": "PFWLT123"
  }'

# Response 201 Created
{
  "success": true,
  "username": "my-wallet-agent-01",
  "password": "generated-secure-password-abc",
  "referral_code": "PFWLT456",
  "referral_link": "https://wallet.purpleflea.com?ref=PFWLT456",
  "message": "Account created. Save your password — it is shown only once.",
  "created_at": "2026-03-06T09:00:00Z"
}

Authenticates with username and password, returning a JWT bearer token valid for 24 hours. Call this at agent startup and whenever you receive a 401 response from authenticated endpoints.

# Request
curl -X POST https://wallet.purpleflea.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "my-wallet-agent-01",
    "password": "generated-secure-password-abc"
  }'

# Response 200 OK
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-03-07T09:00:00Z",
  "username": "my-wallet-agent-01",
  "referral_code": "PFWLT456"
}

Returns all wallet addresses associated with your account, grouped by chain. Each entry includes the address, chain identifier, creation time, and whether it is the primary address for that chain.

# List all wallet addresses
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://wallet.purpleflea.com/api/v1/wallets

# Response 200 OK
{
  "success": true,
  "wallets": [
    {
      "id": "wlt_3f8a2c1d",
      "chain": "eth",
      "address": "0xAbCd1234...5678EfGh",
      "primary": true,
      "label": "Main ETH Wallet",
      "created_at": "2026-03-06T09:00:00Z"
    },
    {
      "id": "wlt_9b2e7f4a",
      "chain": "btc",
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "primary": true,
      "label": "Main BTC Wallet",
      "created_at": "2026-03-06T09:01:00Z"
    },
    {
      "id": "wlt_5c4d8e2f",
      "chain": "sol",
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "primary": true,
      "label": "Main SOL Wallet",
      "created_at": "2026-03-06T09:02:00Z"
    }
  ],
  "total": 3
}

Generates a fresh wallet address for the specified blockchain. The private key is stored securely server-side and never exposed via the API. You can generate multiple addresses per chain for compartmentalization or accounting purposes.

# Generate a new Solana wallet
curl -X POST https://wallet.purpleflea.com/api/v1/wallets/generate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "sol",
    "label": "SOL Trading Wallet",
    "set_primary": false
  }'

# Response 201 Created
{
  "success": true,
  "wallet": {
    "id": "wlt_1a2b3c4d",
    "chain": "sol",
    "address": "4Nd1mBQtrMJVYVfKf2PX8RkELbBWMgrP3Mv1H3H3Ux5",
    "primary": false,
    "label": "SOL Trading Wallet",
    "created_at": "2026-03-06T10:15:00Z"
  }
}

Returns balances for all wallet addresses across every chain in your account. Response includes native token amounts, USD values at current spot prices, and a total portfolio USD value.

# Get all balances
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://wallet.purpleflea.com/api/v1/balance

# Response 200 OK
{
  "success": true,
  "total_usd": 1842.57,
  "balances": {
    "eth": {
      "address": "0xAbCd1234...5678EfGh",
      "native": { "symbol": "ETH", "amount": 0.412, "usd": 1050.24 },
      "tokens": [
        { "symbol": "USDC", "amount": 500.00, "usd": 500.00 }
      ],
      "total_usd": 1550.24
    },
    "btc": {
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "native": { "symbol": "BTC", "amount": 0.00334, "usd": 292.00 },
      "tokens": [],
      "total_usd": 292.00
    },
    "sol": {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "native": { "symbol": "SOL", "amount": 0.018, "usd": 2.43 },
      "tokens": [],
      "total_usd": 2.43
    }
  },
  "refreshed_at": "2026-03-06T10:30:00Z"
}

Returns balance for a single chain. Replace :chain with the chain identifier (e.g. eth, sol, btc). Optionally filter to a specific wallet address if you have multiple addresses per chain.

# Get Ethereum balance (primary address)
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://wallet.purpleflea.com/api/v1/balance/eth

# Get Polygon balance for a specific address
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://wallet.purpleflea.com/api/v1/balance/polygon?address=0xAbCd..."

# Response 200 OK
{
  "success": true,
  "chain": "eth",
  "address": "0xAbCd1234...5678EfGh",
  "native": {
    "symbol": "ETH",
    "amount": 0.412,
    "usd": 1050.24
  },
  "tokens": [
    {
      "symbol": "USDC",
      "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "amount": 500.00,
      "decimals": 6,
      "usd": 500.00
    },
    {
      "symbol": "USDT",
      "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "amount": 0.00,
      "decimals": 6,
      "usd": 0.00
    }
  ],
  "total_usd": 1550.24,
  "refreshed_at": "2026-03-06T10:30:00Z"
}

Broadcasts a signed transfer transaction from your managed wallet to any external address. For ERC-20/SPL token transfers, specify the token field. For native transfers (ETH, BTC, SOL, etc.), omit token.

# Send 0.05 ETH to an external address
curl -X POST https://wallet.purpleflea.com/api/v1/transfer \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "eth",
    "to_address": "0x1234567890abcdef1234567890abcdef12345678",
    "amount": "0.05",
    "priority": "standard"
  }'

# Send 100 USDC on Polygon (low-fee stablecoin transfer)
curl -X POST https://wallet.purpleflea.com/api/v1/transfer \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "polygon",
    "to_address": "0x9876543210fedcba9876543210fedcba98765432",
    "amount": "100",
    "token": "USDC"
  }'

# Response 200 OK
{
  "success": true,
  "tx_id": "txf_8a9b2c3d",
  "chain": "eth",
  "tx_hash": "0xabc123def456...",
  "from_address": "0xAbCd1234...5678EfGh",
  "to_address": "0x1234567890abcdef...",
  "amount": "0.05",
  "token": "ETH",
  "gas_used_gwei": "21000",
  "gas_cost_usd": 0.84,
  "status": "pending",
  "explorer_url": "https://etherscan.io/tx/0xabc123def456...",
  "created_at": "2026-03-06T11:00:00Z"
}

Swaps tokens from one chain to another (or same-chain swaps). Specify source and destination chain, token pair, and amount. If confirm is false, only a quote is returned without execution — use this to check rates before committing.

# Quote only — check rate before executing
curl -X POST https://wallet.purpleflea.com/api/v1/swap \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_chain": "eth",
    "to_chain": "sol",
    "from_token": "ETH",
    "to_token": "SOL",
    "amount": "0.1",
    "confirm": false
  }'

# Response 200 OK (quote only, no funds moved)
{
  "success": true,
  "quote": {
    "from_chain": "eth",
    "to_chain": "sol",
    "from_token": "ETH",
    "to_token": "SOL",
    "from_amount": "0.1",
    "to_amount_estimated": "19.42",
    "rate": 194.2,
    "fee_usd": 0.76,
    "fee_pct": 0.003,
    "gas_estimate_usd": 1.12,
    "slippage_pct": 0.5,
    "min_received": "19.32",
    "route": "ETH -> USDC (Uniswap v3) -> SOL (Wormhole Bridge)",
    "expires_at": "2026-03-06T11:01:00Z"
  }
}

# Execute the swap
curl -X POST https://wallet.purpleflea.com/api/v1/swap \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_chain": "eth",
    "to_chain": "sol",
    "from_token": "ETH",
    "to_token": "SOL",
    "amount": "0.1",
    "confirm": true,
    "slippage_pct": 0.5
  }'

# Response 200 OK (executed)
{
  "success": true,
  "swap": {
    "id": "swp_4f8c2a1e",
    "from_chain": "eth",
    "to_chain": "sol",
    "from_token": "ETH",
    "to_token": "SOL",
    "from_amount": "0.1",
    "to_amount": "19.38",
    "fee_usd": 0.76,
    "tx_hash_out": "0xdef789abc123...",
    "tx_hash_in": "4Nd1mBQtrMJV...",
    "status": "pending",
    "estimated_completion": "2026-03-06T11:04:00Z"
  }
}

# Get last 10 Ethereum transactions
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "https://wallet.purpleflea.com/api/v1/transactions?chain=eth&limit=10"

# Response 200 OK
{
  "success": true,
  "total": 47,
  "limit": 10,
  "offset": 0,
  "transactions": [
    {
      "id": "txf_8a9b2c3d",
      "type": "transfer",
      "chain": "eth",
      "from_address": "0xAbCd1234...",
      "to_address": "0x1234567890...",
      "amount": "0.05",
      "token": "ETH",
      "tx_hash": "0xabc123def456...",
      "gas_cost_usd": 0.84,
      "status": "confirmed",
      "confirmations": 32,
      "explorer_url": "https://etherscan.io/tx/0xabc123...",
      "created_at": "2026-03-06T11:00:00Z",
      "confirmed_at": "2026-03-06T11:01:00Z"
    },
    {
      "id": "swp_4f8c2a1e",
      "type": "swap",
      "from_chain": "eth",
      "to_chain": "sol",
      "from_token": "ETH",
      "to_token": "SOL",
      "from_amount": "0.1",
      "to_amount": "19.38",
      "fee_usd": 0.76,
      "status": "confirmed",
      "created_at": "2026-03-06T10:45:00Z"
    }
  ]
}

Returns the current USD spot price for a token. Replace :token with the token symbol (case-insensitive). Optionally convert to a different quote currency.

# Get ETH price in USD (no auth required)
curl https://wallet.purpleflea.com/api/v1/price/eth

# Get SOL price quoted in BTC
curl "https://wallet.purpleflea.com/api/v1/price/sol?quote=btc"

# Response 200 OK
{
  "success": true,
  "token": "ETH",
  "quote": "USD",
  "price": 2551.82,
  "change_24h_pct": 1.48,
  "change_7d_pct": -3.21,
  "market_cap_usd": 306800000000,
  "volume_24h_usd": 14200000000,
  "updated_at": "2026-03-06T11:30:00Z"
}

Supported Tokens

Returns your referral code, list of referred agents, total earnings to date, and pending (uncleared) earnings.

# Get referral stats
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://wallet.purpleflea.com/api/v1/referrals

# Response 200 OK
{
  "success": true,
  "referral_code": "PFWLT456",
  "referral_link": "https://wallet.purpleflea.com?ref=PFWLT456",
  "referred_count": 7,
  "total_earned_usd": 12.84,
  "pending_usd": 1.20,
  "rate_pct": 10,
  "referrals": [
    {
      "username": "trading-bot-42",
      "joined_at": "2026-02-14T08:00:00Z",
      "swap_volume_usd": 28400,
      "earned_from_usd": 8.52
    },
    {
      "username": "arb-agent-7",
      "joined_at": "2026-02-28T15:30:00Z",
      "swap_volume_usd": 4200,
      "earned_from_usd": 1.26
    }
  ]
}

Initiates a withdrawal from your managed wallet to an external address. All withdrawals are logged and broadcast immediately. Referral earnings can be withdrawn to any chain that supports USDC.

# Withdraw 25 USDC referral earnings to Ethereum
curl -X POST https://wallet.purpleflea.com/api/v1/withdraw \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "eth",
    "to_address": "0x9876543210fedcba9876543210fedcba98765432",
    "amount": "25.00",
    "token": "USDC",
    "memo": "Referral earnings withdrawal March 2026"
  }'

# Response 200 OK
{
  "success": true,
  "withdrawal": {
    "id": "wdr_7c2a9f1b",
    "chain": "eth",
    "to_address": "0x9876543210fedcba...",
    "amount": "25.00",
    "token": "USDC",
    "tx_hash": "0x789abc123def...",
    "gas_cost_usd": 0.92,
    "status": "pending",
    "explorer_url": "https://etherscan.io/tx/0x789abc...",
    "created_at": "2026-03-06T12:00:00Z"
  }
}