Sponge Wallet API — Agent Skills Guide (OpenClawd Edition)

This skill gives Clawd access to the Sponge Wallet REST API — a full crypto wallet with swaps, bridges, trading, payments, banking, and paid external services.

Quick Start

# Base URL
SPONGE_API_URL="https://api.wallet.paysponge.com"
SPONGE_API_KEY="sponge_live_..."  # set in .env or export

# Required header on every request
# Sponge-Version: 0.2.2
# Authorization: Bearer $SPONGE_API_KEY
# Content-Type: application/json

What You Can Do

1. Manage crypto — check balances, transfer tokens (EVM/Solana/Tempo), swap on Solana/Base/Ethereum/Polygon/Arbitrum/Tempo, bridge cross-chain
2. Create payment links — generate reusable x402 payment URLs
3. Access paid external services — search, image gen, web scraping, AI, data enrichment
4. Banking — KYC onboarding, virtual bank accounts (receive USD as USDC), off-ramp to bank
5. Trade — Polymarket prediction markets, Hyperliquid perpetuals
6. Checkout — shop from online stores via URL checkout
7. Store cards — encrypted card data for checkout, virtual cards, Sponge Card
8. Fiat onramp — buy crypto with card/bank via Stripe or Coinbase

Top-Level API Reference

Base:   https://api.wallet.paysponge.com
Auth:   Authorization: Bearer <SPONGE_API_KEY>
Ver:    Sponge-Version: 0.2.2  (REQUIRED on every request)

Paid services (search, image gen, scraping, AI, data, etc.):
  GET  /api/discover                     -> find services by query/category
  GET  /api/discover/:serviceId          -> get endpoints, params, pricing
  POST /api/paid/fetch                   -> call service (auto-selects x402 or MPP)
  POST /api/x402/fetch                   -> call service (x402 USDC only)
  POST /api/mpp/fetch                    -> call service (MPP on Tempo)

Wallet & tokens:
  GET  /api/balances                     -> get all balances
  POST /api/transfers/evm                -> EVM transfer (ETH/USDC)
  POST /api/transfers/solana             -> Solana transfer (SOL/USDC)
  POST /api/transfers/tempo              -> Tempo transfer (pathUSD etc.)
  POST /api/transactions/swap            -> Solana/EVM swap
  POST /api/transactions/base-swap       -> Base swap
  POST /api/transactions/tempo-swap      -> Tempo swap
  POST /api/transactions/bridge          -> cross-chain bridge
  GET  /api/solana/tokens                -> list SPL tokens
  GET  /api/solana/tokens/search         -> search Jupiter token list
  GET  /api/transactions/status/:txHash  -> transaction status
  GET  /api/transactions/history         -> transaction history

Trading:
  POST /api/polymarket                   -> Polymarket prediction markets
  POST /api/hyperliquid                  -> Hyperliquid perps/spot

Banking:
  POST /api/bank/onboard                 -> start KYC
  GET  /api/bank/status                  -> KYC status
  POST /api/bank/virtual-account         -> create virtual bank account
  GET  /api/bank/external-accounts       -> list linked bank accounts
  POST /api/bank/external-accounts       -> link bank account
  POST /api/bank/send                    -> off-ramp USD to bank

Cards & checkout:
  POST /api/cards                        -> fetch user's card
  POST /api/virtual-cards                -> issue per-transaction virtual card
  POST /api/checkout                     -> URL checkout from online stores
  GET  /api/checkout/:sessionId          -> checkout status
  POST /api/credit-cards                 -> store encrypted card data
  POST /api/onramp/crypto                -> fiat-to-crypto onramp link

Planning:
  POST /api/plans/submit                 -> submit multi-step plan
  POST /api/plans/approve                -> approve and execute plan
  POST /api/trades/propose               -> propose single swap

Authentication

For AI Agents — Use register, NOT login

Register with agent-first mode to get an API key immediately:

curl -sS -X POST "https://api.wallet.paysponge.com/api/agents/register" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clawd","agentFirst":true}'

Returns apiKey immediately in agent-first mode. Store it in ~/.spongewallet/credentials.json.

Human Login (only for existing accounts)

# Step 1: Request device code
curl -sS -X POST "https://api.wallet.paysponge.com/api/oauth/device/authorization" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"spongewallet-skill"}'

# Step 2: Poll for token
curl -sS -X POST "https://api.wallet.paysponge.com/api/oauth/device/token" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{
    "grantType":"urn:ietf:params:oauth:grant-type:device_code",
    "deviceCode":"<deviceCode>",
    "clientId":"spongewallet-skill"
  }'

Standard Credential Storage

Store credentials in ~/.spongewallet/credentials.json:

{
  "apiKey": "sponge_live_...",
  "claimCode": "ABCD-1234",
  "claimUrl": "https://wallet.paysponge.com/device?code=ABCD-1234"
}

Common Operations

Check Balances

curl -sS "https://api.wallet.paysponge.com/api/balances?chain=base" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2"

Transfer USDC on Base

curl -sS -X POST "https://api.wallet.paysponge.com/api/transfers/evm" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"chain":"base","to":"0x...","amount":"10","currency":"USDC"}'

Swap on Solana

curl -sS -X POST "https://api.wallet.paysponge.com/api/transactions/swap" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"chain":"solana","inputToken":"SOL","outputToken":"USDC","amount":"0.1","slippageBps":50}'

Paid Services (3-Step Flow)

Step 1 — Find a service:

curl -sS "https://api.wallet.paysponge.com/api/discover?query=web+scraping" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2"

Step 2 — Get service details (DO NOT SKIP):

curl -sS "https://api.wallet.paysponge.com/api/discover/{serviceId}" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2"

Step 3 — Call the endpoint:

curl -sS -X POST "https://api.wallet.paysponge.com/api/paid/fetch" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url_from_step2>","method":"POST","body":{...},"chain":"base"}'

Bridge USDC to Hyperliquid for Trading

curl -sS -X POST "https://api.wallet.paysponge.com/api/transactions/bridge" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"sourceChain":"base","destinationChain":"hyperliquid","token":"USDC","amount":"50"}'

Trade on Hyperliquid

curl -sS -X POST "https://api.wallet.paysponge.com/api/hyperliquid" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Sponge-Version: 0.2.2" \
  -H "Content-Type: application/json" \
  -d '{"action":"order","symbol":"ETH","side":"buy","type":"limit","amount":"0.1","price":"3000"}'

Chain Reference

Supported chains: ethereum, base, polygon, arbitrum-one, tempo, solana

Error Handling

Status	Meaning	Common Cause
400	Bad Request	Missing/invalid fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	Permission denied
404	Not Found	Resource does not exist
429	Rate Limited	Too many requests
500	Server Error	Transient; retry later

Security

• Never share your API key in logs, posts, or screenshots
• Store API key in environment variable SPONGE_API_KEY
• Rotate the key if exposure is suspected
• Use sponge_test_* keys for development, sponge_live_* for production

Integration with Clawd

The Sponge Wallet can be used by Clawd in two ways:

1. Direct REST calls — use fetch_url tool or curl via shell to hit the Sponge API
2. MCP Server — connect to https://api.wallet.paysponge.com/mcp with Authorization: Bearer $SPONGE_API_KEY header for structured tool access