--- name: sponge-wallet version: 1.0.0 description: Manage crypto wallets, transfers, swaps, and balances via the Sponge Wallet API. homepage: https://wallet.paysponge.com user-invocable: true metadata: {"openclaw":{"emoji":"\ud83e\uddfd","category":"finance","primaryEnv":"SPONGE_API_KEY","requires":{"env":["SPONGE_API_KEY"]}}} --- ``` SPONGE WALLET API QUICK REFERENCE v1.0.0 Base: https://api.wallet.paysponge.com Auth: Authorization: Bearer Docs: This file is canonical (skills guide + params) Key endpoints: POST /api/agents/register -> register (no auth) POST /api/oauth/device/authorization -> device login start (humans) POST /api/oauth/device/token -> device token poll (agents + humans) GET /api/balances -> get balances (includes Polymarket USDC.e) POST /api/transfers/evm -> EVM transfer (ETH/USDC) POST /api/transfers/solana -> Solana transfer (SOL/USDC) POST /api/transactions/swap -> Solana swap POST /api/transactions/base-swap -> Base swap (0x) POST /api/transactions/bridge -> Bridge (deBridge) 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 POST /api/funding-requests -> request funding from owner POST /api/wallets/withdraw-to-main -> withdraw to owner POST /api/x402/fetch -> x402 fetch (auto-pay 402s) GET /api/x402/discover -> discover x402 services (Bazaar) POST /api/polymarket -> Polymarket prediction market trading POST /api/checkout -> Amazon checkout (initiate purchase) GET /api/checkout/:sessionId -> checkout status DELETE /api/checkout/:sessionId -> cancel checkout GET /api/checkout/history -> checkout history POST /api/checkout/amazon-search -> search Amazon products Rules: use register (agents), never login | store key in ~/.spongewallet/credentials.json | requests are JSON Errors: HTTP status + JSON error message ``` # Sponge Wallet API - Agent Skills Guide This skill is **doc-only**. There is no local CLI. Agents must call the Sponge Wallet REST API directly. ## Why the steps matter (short rationale) - **Register vs login**: agents create a new managed wallet tied to a human owner. That owner must explicitly claim the agent. Login is only for humans who already have an account. - **Claim URL**: ensures the human owner explicitly links the agent to their account and controls allowlists/funding. - **Credential persistence**: the `apiKey` is returned once (immediately for agent-first mode, or after device approval for standard mode). If you lose it, you must re-register or re-authenticate. ## Standard credential storage (required) Store the API key in **one canonical location**: - `~/.spongewallet/credentials.json` Recommended file contents: ```json { "apiKey": "sponge_live_...", "claimCode": "ABCD-1234", "claimUrl": "https://wallet.paysponge.com/device?code=ABCD-1234" } ``` Optional environment export (runtime convenience): ```bash export SPONGE_API_KEY="$(jq -r .apiKey ~/.spongewallet/credentials.json)" ``` ## Base URL & Auth - Base URL: `https://api.wallet.paysponge.com` - Auth header: `Authorization: Bearer ` - Content-Type: `application/json` Quick env setup: ```bash export SPONGE_API_URL="https://api.wallet.paysponge.com" export SPONGE_API_KEY="$(jq -r .apiKey ~/.spongewallet/credentials.json)" ``` ## CRITICAL: AI Agents Must Use `register`, NOT `login` ### 1) Agent Registration (AI agents only) There are two modes: - **Standard device flow** (default): human must approve before the API key is returned. - **Agent-first** (`agentFirst: true`): agent receives the API key immediately, and the human can claim later. **Step 1 — Start registration (agent-first recommended)** ```bash curl -sS -X POST "$SPONGE_API_URL/api/agents/register" \ -H "Content-Type: application/json" \ -d '{ "name":"YourAgentName", "agentFirst": true, "testnet": true }' ``` Response includes: - `verificationUriComplete` (claim URL for the human owner) - `claimCode`, `deviceCode`, `expiresIn`, `interval`, `claimText` - `apiKey` (returned immediately in agent-first mode) Store `apiKey`, `claimCode`, and `verificationUriComplete` (as `claimUrl`) in `~/.spongewallet/credentials.json` so a human can claim later if context resets. **Step 2 — Send the claim URL to the human owner** They log in, optionally post the tweet text, and approve the agent. Claim link format: - `verificationUriComplete` (example path: `/device?code=ABCD-1234`) - The base URL is the frontend (prod or local), so just pass the full `verificationUriComplete` to the human. **Step 3 — Poll for completion (standard device flow only)** ```bash curl -sS -X POST "$SPONGE_API_URL/api/oauth/device/token" \ -H "Content-Type: application/json" \ -d '{ "grantType":"urn:ietf:params:oauth:grant-type:device_code", "deviceCode":"", "clientId":"spongewallet-skill" }' ``` On success, the response includes `apiKey`. Save it to `~/.spongewallet/credentials.json` and use it as `SPONGE_API_KEY`. Note: In **agent-first mode**, you already have the `apiKey` from Step 1. The device token will remain pending until the human claims. ### 2) Human Login (existing accounts only) **Phase 1 — Request device code** ```bash curl -sS -X POST "$SPONGE_API_URL/api/oauth/device/authorization" \ -H "Content-Type: application/json" \ -d '{ "clientId":"spongewallet-skill", "scope":"wallet:read wallet:write transaction:sign transaction:write" }' ``` **Phase 2 — Poll for token** (same endpoint as agents) ```bash curl -sS -X POST "$SPONGE_API_URL/api/oauth/device/token" \ -H "Content-Type: application/json" \ -d '{ "grantType":"urn:ietf:params:oauth:grant-type:device_code", "deviceCode":"", "clientId":"spongewallet-skill" }' ``` ## Tool Call Pattern All tool calls are plain REST requests with JSON payloads. **Common headers** ```bash -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json" ``` **Agent ID note:** `agentId` is optional for API key auth. It is only required when using a user session (e.g., Privy-based auth) or when explicitly operating on a different agent. ### Tool -> Endpoint Map | Tool | Method | Path | Params/Body | |------|--------|------|-------------| | `get_balance` | GET | `/api/balances` | Query: `chain`, `allowedChains`, `onlyUsdc` | | `get_solana_tokens` | GET | `/api/solana/tokens` | Query: `chain` | | `search_solana_tokens` | GET | `/api/solana/tokens/search` | Query: `query`, `limit` | | `evm_transfer` | POST | `/api/transfers/evm` | Body: `chain`, `to`, `amount`, `currency` | | `solana_transfer` | POST | `/api/transfers/solana` | Body: `chain`, `to`, `amount`, `currency` | | `solana_swap` | POST | `/api/transactions/swap` | Body: `chain`, `inputToken`, `outputToken`, `amount`, `slippageBps` | | `base_swap` | POST | `/api/transactions/base-swap` | Body: `chain`, `inputToken`, `outputToken`, `amount`, `slippageBps` | | `bridge` | POST | `/api/transactions/bridge` | Body: `sourceChain`, `destinationChain`, `token`, `amount`, `destinationToken`, `recipientAddress` | | `get_transaction_status` | GET | `/api/transactions/status/{txHash}` | Query: `chain` | | `get_transaction_history` | GET | `/api/transactions/history` | Query: `limit`, `chain` | | `request_funding` | POST | `/api/funding-requests` | Body: `amount`, `reason`, `chain`, `currency` | | `withdraw_to_main_wallet` | POST | `/api/wallets/withdraw-to-main` | Body: `chain`, `amount`, `currency` | | `x402_fetch` | POST | `/api/x402/fetch` | Body: `url`, `method`, `headers`, `body`, `preferred_chain` | | `discover_x402_services` | GET | `/api/x402/discover` | Query: `type`, `limit`, `offset`, `include_catalog` | | `polymarket` | POST | `/api/polymarket` | Body: `action`, + action-specific params (see below) | | `amazon_checkout` | POST | `/api/checkout` | Body: `checkoutUrl`, `amazonAccountId`, `shippingAddress`, `dryRun`, `clearCart` | | `get_checkout_status` | GET | `/api/checkout/{sessionId}` | Query: `agentId` (optional) | | `get_checkout_history` | GET | `/api/checkout/history` | Query: `agentId`, `limit`, `offset` | | `amazon_search` | POST | `/api/checkout/amazon-search` | Body: `query`, `maxResults`, `region` | Note: request bodies use camelCase (e.g., `inputToken`, `slippageBps`). ### Polymarket Actions The `polymarket` endpoint is a unified tool. Pass `action` plus action-specific parameters: | Action | Description | Required Params | Optional Params | |--------|-------------|-----------------|-----------------| | `status` | Check Polymarket account status and USDC.e balance | — | — | | `markets` | Search prediction markets | — | `query`, `limit` | | `positions` | View current market positions | — | — | | `orders` | View open and recent orders | — | — | | `order` | Place a buy/sell order | `outcome`, `side`, `size`, `price` | `market_slug` or `token_id`, `order_type` | | `cancel` | Cancel an open order | `order_id` | — | | `set_allowances` | Reset token approvals | — | — | | `withdraw` | Withdraw USDC.e from Safe to any address | `to_address`, `amount` | — | **Order params:** - `market_slug`: Market URL slug (e.g., `"will-bitcoin-hit-100k"`) — use this OR `token_id` - `token_id`: Polymarket condition token ID — use this OR `market_slug` - `outcome`: `"yes"` or `"no"` - `side`: `"buy"` or `"sell"` - `size`: Number of shares (e.g., `10`) - `price`: Probability price 0.0–1.0 (e.g., `0.65` = 65 cents per share) - `order_type`: `"GTC"` (default), `"GTD"`, `"FOK"`, `"FAK"` **Scopes:** Trade actions (`order`, `cancel`, `set_allowances`, `withdraw`) require `polymarket:trade` scope. Read actions (`status`, `markets`, `positions`, `orders`) require `polymarket:read`. **Auto-provisioning:** The Polymarket Safe wallet is created automatically on first use. No manual setup needed. ### Amazon Checkout Purchase products from Amazon using a configured Amazon account. **Prerequisites:** - An Amazon account must be configured via the dashboard or `/api/agents/:id/amazon-accounts` endpoints - A shipping address must be set (inline or via `/api/agents/:id/shipping-addresses`) **Async workflow:** 1. Initiate checkout with `POST /api/checkout` — returns a `sessionId` 2. Wait ~60 seconds for the initial checkout process 3. Poll `GET /api/checkout/:sessionId` every 10 seconds until status is `completed` or `failed` **Status progression:** `pending` → `in_progress` → `completed` | `failed` | `cancelled` **Key options:** - `dryRun: true` — stops before placing the order (useful for testing or previewing total cost) - `clearCart: true` — clears the Amazon cart before adding the product (default behavior) **Scopes:** Checkout actions require `amazon_checkout` scope on the API key. ## Quick Start ### 1) Register (agents only) ```bash curl -sS -X POST "$SPONGE_API_URL/api/agents/register" \ -H "Content-Type: application/json" \ -d '{ "name":"YourAgentName", "agentFirst": true, "testnet": true }' ``` Share the claim URL with your human, then store the `apiKey` immediately (agent-first). For standard device flow, poll for the token after approval. ### 2) Check balance ```bash curl -sS "$SPONGE_API_URL/api/balances?chain=base" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Accept: application/json" ``` ### 3) Transfer USDC on Base ```bash curl -sS -X POST "$SPONGE_API_URL/api/transfers/evm" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chain":"base", "to":"0x...", "amount":"10", "currency":"USDC" }' ``` ## Examples ### Swap tokens on Solana ```bash curl -sS -X POST "$SPONGE_API_URL/api/transactions/swap" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chain":"solana", "inputToken":"SOL", "outputToken":"BONK", "amount":"0.5", "slippageBps":100 }' ``` ### Swap tokens on Base ```bash curl -sS -X POST "$SPONGE_API_URL/api/transactions/base-swap" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "chain":"base", "inputToken":"ETH", "outputToken":"USDC", "amount":"0.1", "slippageBps":50 }' ``` ### Bridge tokens cross-chain ```bash curl -sS -X POST "$SPONGE_API_URL/api/transactions/bridge" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sourceChain":"solana", "destinationChain":"base", "token":"SOL", "amount":"0.1", "destinationToken":"ETH" }' ``` ### Check transaction status ```bash curl -sS "$SPONGE_API_URL/api/transactions/status/0xabc123...?chain=base" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Accept: application/json" ``` ### Polymarket — Check status ```bash curl -sS -X POST "$SPONGE_API_URL/api/polymarket" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"status"}' ``` ### Polymarket — Search markets ```bash curl -sS -X POST "$SPONGE_API_URL/api/polymarket" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"markets","query":"bitcoin","limit":5}' ``` ### Polymarket — Place an order ```bash curl -sS -X POST "$SPONGE_API_URL/api/polymarket" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action":"order", "market_slug":"will-bitcoin-hit-100k", "outcome":"yes", "side":"buy", "size":10, "price":0.65 }' ``` ### Polymarket — View positions ```bash curl -sS -X POST "$SPONGE_API_URL/api/polymarket" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"positions"}' ``` ### Polymarket — Withdraw USDC.e ```bash curl -sS -X POST "$SPONGE_API_URL/api/polymarket" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action":"withdraw", "to_address":"0x...", "amount":"10.00" }' ``` ### Amazon Checkout — Initiate purchase ```bash curl -sS -X POST "$SPONGE_API_URL/api/checkout" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "checkoutUrl":"https://www.amazon.com/dp/B0EXAMPLE", "dryRun":true, "clearCart":true }' ``` ### Amazon Checkout — Poll status ```bash curl -sS "$SPONGE_API_URL/api/checkout/" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Accept: application/json" ``` ### Amazon Checkout — Get history ```bash curl -sS "$SPONGE_API_URL/api/checkout/history?limit=10" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Accept: application/json" ``` ### Amazon — Search products ```bash curl -sS -X POST "$SPONGE_API_URL/api/checkout/amazon-search" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"wireless mouse","maxResults":5}' ``` ### x402 Fetch (auto-pay for paid APIs) ```bash curl -sS -X POST "$SPONGE_API_URL/api/x402/fetch" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url":"https://api.paysponge.com/api/services/purchase/svc_abc123/polymarket/markets?search=bitcoin&limit=5", "method":"GET", "preferred_chain":"base" }' ``` The `x402_fetch` tool handles the entire payment flow automatically: 1. Makes the HTTP request to the specified URL 2. If the service returns 402 Payment Required, extracts payment requirements 3. Creates and signs a USDC payment using the agent's wallet (Base or Solana) 4. Retries the request with the Payment-Signature header 5. Returns the final API response with `payment_made` and `payment_details` ### Discover x402 services (Bazaar) ```bash curl -sS "$SPONGE_API_URL/api/x402/discover?limit=10" \ -H "Authorization: Bearer $SPONGE_API_KEY" \ -H "Accept: application/json" ``` Returns available x402-enabled services from the Bazaar and Sponge's curated catalog. Use this to find paid APIs before calling `x402_fetch`. ## Chain Reference **Test keys** (`sponge_test_*`): `sepolia`, `base-sepolia`, `solana-devnet`, `tempo` **Live keys** (`sponge_live_*`): `ethereum`, `base`, `solana` ## Error Responses Errors return JSON with an error message and HTTP status: ```json {"error":"message"} ``` | Status | Meaning | Common Cause | |--------|---------|--------------| | 400 | Bad Request | Missing/invalid fields | | 401 | Unauthorized | Missing or invalid API key | | 403 | Forbidden | Address not in allowlist or permission denied | | 404 | Not Found | Resource does not exist | | 409 | Conflict | Duplicate action | | 429 | Rate Limited | Too many requests (back off + retry) | | 500 | Server Error | Transient; retry later | ## Security - Never share your API key in logs, posts, or screenshots. - Store your API key in `~/.spongewallet/credentials.json` and restrict file permissions. - Rotate the key if exposure is suspected. --- Built for agents.