Sponge Wallet

SPONGE WALLET API QUICK REFERENCE v1.0.0
Base:   https://api.wallet.paysponge.com
Auth:   Authorization: Bearer <SPONGE_API_KEY>
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
  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/payments                -> create x402 payment

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 approve 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 device token response returns the apiKey once. 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:

{
  "apiKey": "sponge_live_..."
}

Optional environment export (runtime convenience):

export SPONGE_API_KEY="$(jq -r .apiKey ~/.spongewallet/credentials.json)"

Base URL & Auth

• Base URL: https://api.wallet.paysponge.com
• Auth header: Authorization: Bearer <SPONGE_API_KEY>
• Content-Type: application/json

Quick env setup:

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)

Step 1 — Start registration

curl -sS -X POST "$SPONGE_API_URL/api/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"YourAgentName"}'

Response includes:

• verificationUriComplete (claim URL for the human owner)
• claimCode, deviceCode, expiresIn, interval, claimText

Step 2 — Send the claim URL to the human owner They log in, optionally post the tweet text, and approve the agent.

Step 3 — Poll for completion

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":"<deviceCode>",
    "clientId":"spongewallet-skill"
  }'

On success, the response includes apiKey. Save it to ~/.spongewallet/credentials.json and use it as SPONGE_API_KEY.

2) Human Login (existing accounts only)

Phase 1 — Request device code

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)

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":"<deviceCode>",
    "clientId":"spongewallet-skill"
  }'

Tool Call Pattern

All tool calls are plain REST requests with JSON payloads.

Common headers

-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

Note: request bodies use camelCase (e.g., inputToken, slippageBps).

Quick Start

1) Register (agents only)

curl -sS -X POST "$SPONGE_API_URL/api/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"YourAgentName"}'

Share the claim URL with your human, then poll for the token and store the apiKey.

2) Check balance

curl -sS "$SPONGE_API_URL/api/balances?chain=base" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Accept: application/json"

3) Transfer USDC on Base

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

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

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

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

curl -sS "$SPONGE_API_URL/api/transactions/status/0xabc123...?chain=base" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Accept: application/json"

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:

{"error":"message"}

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.