Sponge Wallet

Manage crypto wallets, transfers, swaps, and balances via the Sponge Wallet API.

Security Scan

The skill largely matches its description (wallet operations via the Sponge Wallet API) but there are a few inconsistencies and operational choices that increase risk (notably agent-first registration that grants an API key immediately, instructions to persist keys to disk, and a mismatch between declared config paths and the SKILL.md).

Purpose & Capability

Name, description, and required credential (SPONGE_API_KEY) line up with a REST-API-only crypto wallet skill. No unrelated binaries or extra cloud creds are requested.

Instruction Scope

SKILL.md instructs agents to call many wallet endpoints, to store the API key and claim info in ~/.spongewallet/credentials.json, and to use an 'agent-first' registration flow that returns an apiKey immediately. The skill asks agents to send claim URLs to humans and optionally post tweet text. The instructions reference reading and writing a home-folder file (credentials.json) even though the registry metadata lists no required config paths.

Install Mechanism

This is an instruction-only skill with no install spec and no code files — lowest install risk.

Credentials

Only SPONGE_API_KEY is required (proportionate). However, SKILL.md also expects/encourages reading/writing ~/.spongewallet/credentials.json and exporting SPONGE_API_URL at runtime; that file path is not declared in the registry metadata, creating a metadata/instruction mismatch that users should be aware of.

Persistence & Privilege

always:false (good), but the instructions explicitly recommend agent-first registration which returns an API key immediately and to persist it locally. Combined with normal autonomous invocation (disable-model-invocation: false), an agent could act with the key before a human claims or approves — this increases the blast radius for a misbehaving or compromised skill.

What to consider before installing

This skill appears to do what it says (manage wallets via the Sponge Wallet API), but pay attention before installing: 1) SKILL.md tells agents to use an 'agent-first' registration flow that returns an API key immediately — that means an agent could perform transactions before a human explicitly claims the wallet. If you require human approval, prefer the standard device flow. 2) The skill instructs writing the API key to ~/.spongewallet/credentials.json (and exporting it). Confirm you are comfortable storing a live crypto API key on disk; consider using least-privilege keys or isolated accounts and rotate keys frequently. 3) The registry metadata did not declare the ~/.spongewallet config path even though the instructions use it — treat that as a minor inconsistency and verify how your agent runtime will handle the file. 4) Ensure the SPONGE_API_KEY you provide has only the permissions you expect; if possible test on testnet keys first. 5) Verify the skill's source/homepage before granting any live keys. If you need stricter guarantees (human-in-the-loop for any transfer or disabling agent-autonomy), require those controls before installing.

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 (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:

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

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)

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)

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)

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.

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

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

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)

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

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"

Polymarket — Check status

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

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

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

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

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

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

curl -sS "$SPONGE_API_URL/api/checkout/<sessionId>" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Accept: application/json"

Amazon Checkout — Get history

curl -sS "$SPONGE_API_URL/api/checkout/history?limit=10" \
  -H "Authorization: Bearer $SPONGE_API_KEY" \
  -H "Accept: application/json"

Amazon — Search products

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)

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)

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:

{"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.