Agent Guide

This page provides instructions for using the Sponge Wallet skill for wallet management, token transfers, swaps, and x402 paid API access.

For AI Agents

https://wallet.paysponge.com/skill.md

clawdhub install sponge-wallet

Doc-Only Skill

This skill has no local CLI. Agents call the Sponge Wallet REST API directly using the documentation above.

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

Authentication Flow

Agents Must Use Register, NOT Login

AI agents create a new managed wallet tied to a human owner. The owner must explicitly approve the agent. Login is only for humans with existing accounts.

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

Step 2: Send Claim URL to Owner

The human owner must visit the claim URL to 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, save the apiKey to ~/.spongewallet/credentials.json.

API Endpoints

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`
`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`
`create_x402_payment`	POST	`/api/x402/payments`	Body: `chain`, `to`, `token`, `amount`, `decimals`, `valid_for_seconds`

Allowlist Required

Recipients must be pre-approved in the owner's allowlist. Transfers to unapproved addresses will fail.

Quick Start Examples

Check Balance

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

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

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

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

Supported Chains

Mainnet (Live Keys)

Chain	Key Prefix	Currency
Ethereum	`sponge_live_*`	ETH, USDC
Base	`sponge_live_*`	ETH, USDC
Solana	`sponge_live_*`	SOL, USDC

Testnet (Test Keys)

Chain	Key Prefix	Currency
Sepolia	`sponge_test_*`	ETH, USDC
Base Sepolia	`sponge_test_*`	ETH, USDC
Solana Devnet	`sponge_test_*`	SOL, USDC
Tempo	`sponge_test_*`	pathUSD

Error Responses

Errors return JSON with HTTP status:

{"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
429	Rate Limited	Too many requests (back off + retry)
500	Server Error	Transient; retry later

Credential Storage

Store the API key in the canonical location:

~/.spongewallet/credentials.json

File contents:

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

Security

Never share your API key in logs, posts, or screenshots. Rotate the key if exposure is suspected.

For Humans

If you're a human developer or wallet owner, you can manage your wallets, agents, and settings through the web dashboard:

Sponge Wallet Dashboard

Create wallets, manage agents, set spending limits, configure allowlists, and monitor transactions.

The dashboard provides:

Wallet Management - View balances across all chains
Agent Control - Create agents, generate API keys, approve funding requests
Security Settings - Configure allowlists and spending limits
Transaction History - Monitor all agent activity

For programmatic access and SDK usage, see the Quickstart guide.

Resources

Web Dashboard

Manage wallets and agents.

Skill Documentation

Complete machine-readable API reference.

Telegram Support

Join the community for help.