my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: sponge-wallet
#3	version: 0.2.2
#4	description: Crypto wallet, token swaps, cross-chain bridges, and access to paid external services (search, image gen, web scraping, AI, and more) via x402 payments.
#5	homepage: https://wallet.paysponge.com
#6	metadata:
#7	openclaw:
#8	emoji: "\U0001F9FD"
#9	category: finance
#10	primaryEnv: SPONGE_API_KEY
#11	requires:
#12	env:
#13	- SPONGE_API_KEY
#14	---
#15
#16	# Sponge Wallet API — Agent Skills Guide (OpenClawd Edition)
#17
#18	This skill gives Clawd access to the Sponge Wallet REST API — a full crypto wallet
#19	with swaps, bridges, trading, payments, banking, and paid external services.
#20
#21	## Quick Start
#22
#23	```bash
#24	# Base URL
#25	SPONGE_API_URL="https://api.wallet.paysponge.com"
#26	SPONGE_API_KEY="sponge_live_..." # set in .env or export
#27
#28	# Required header on every request
#29	# Sponge-Version: 0.2.2
#30	# Authorization: Bearer $SPONGE_API_KEY
#31	# Content-Type: application/json
#32	```
#33
#34	## What You Can Do
#35
#36	1. Manage crypto — check balances, transfer tokens (EVM/Solana/Tempo), swap on Solana/Base/Ethereum/Polygon/Arbitrum/Tempo, bridge cross-chain
#37	2. Create payment links — generate reusable x402 payment URLs
#38	3. Access paid external services — search, image gen, web scraping, AI, data enrichment
#39	4. Banking — KYC onboarding, virtual bank accounts (receive USD as USDC), off-ramp to bank
#40	5. Trade — Polymarket prediction markets, Hyperliquid perpetuals
#41	6. Checkout — shop from online stores via URL checkout
#42	7. Store cards — encrypted card data for checkout, virtual cards, Sponge Card
#43	8. Fiat onramp — buy crypto with card/bank via Stripe or Coinbase
#44
#45	## Top-Level API Reference
#46
#47	```
#48	Base: https://api.wallet.paysponge.com
#49	Auth: Authorization: Bearer <SPONGE_API_KEY>
#50	Ver: Sponge-Version: 0.2.2 (REQUIRED on every request)
#51
#52	Paid services (search, image gen, scraping, AI, data, etc.):
#53	GET /api/discover -> find services by query/category
#54	GET /api/discover/:serviceId -> get endpoints, params, pricing
#55	POST /api/paid/fetch -> call service (auto-selects x402 or MPP)
#56	POST /api/x402/fetch -> call service (x402 USDC only)
#57	POST /api/mpp/fetch -> call service (MPP on Tempo)
#58
#59	Wallet & tokens:
#60	GET /api/balances -> get all balances
#61	POST /api/transfers/evm -> EVM transfer (ETH/USDC)
#62	POST /api/transfers/solana -> Solana transfer (SOL/USDC)
#63	POST /api/transfers/tempo -> Tempo transfer (pathUSD etc.)
#64	POST /api/transactions/swap -> Solana/EVM swap
#65	POST /api/transactions/base-swap -> Base swap
#66	POST /api/transactions/tempo-swap -> Tempo swap
#67	POST /api/transactions/bridge -> cross-chain bridge
#68	GET /api/solana/tokens -> list SPL tokens
#69	GET /api/solana/tokens/search -> search Jupiter token list
#70	GET /api/transactions/status/:txHash -> transaction status
#71	GET /api/transactions/history -> transaction history
#72
#73	Trading:
#74	POST /api/polymarket -> Polymarket prediction markets
#75	POST /api/hyperliquid -> Hyperliquid perps/spot
#76
#77	Banking:
#78	POST /api/bank/onboard -> start KYC
#79	GET /api/bank/status -> KYC status
#80	POST /api/bank/virtual-account -> create virtual bank account
#81	GET /api/bank/external-accounts -> list linked bank accounts
#82	POST /api/bank/external-accounts -> link bank account
#83	POST /api/bank/send -> off-ramp USD to bank
#84
#85	Cards & checkout:
#86	POST /api/cards -> fetch user's card
#87	POST /api/virtual-cards -> issue per-transaction virtual card
#88	POST /api/checkout -> URL checkout from online stores
#89	GET /api/checkout/:sessionId -> checkout status
#90	POST /api/credit-cards -> store encrypted card data
#91	POST /api/onramp/crypto -> fiat-to-crypto onramp link
#92
#93	Planning:
#94	POST /api/plans/submit -> submit multi-step plan
#95	POST /api/plans/approve -> approve and execute plan
#96	POST /api/trades/propose -> propose single swap
#97	```
#98
#99	## Authentication
#100
#101	### For AI Agents — Use `register`, NOT `login`
#102
#103	Register with agent-first mode to get an API key immediately:
#104
#105	```bash
#106	curl -sS -X POST "https://api.wallet.paysponge.com/api/agents/register" \
#107	-H "Sponge-Version: 0.2.2" \
#108	-H "Content-Type: application/json" \
#109	-d '{"name":"Clawd","agentFirst":true}'
#110	```
#111
#112	Returns `apiKey` immediately in agent-first mode. Store it in `~/.spongewallet/credentials.json`.
#113
#114	### Human Login (only for existing accounts)
#115
#116	```bash
#117	# Step 1: Request device code
#118	curl -sS -X POST "https://api.wallet.paysponge.com/api/oauth/device/authorization" \
#119	-H "Sponge-Version: 0.2.2" \
#120	-H "Content-Type: application/json" \
#121	-d '{"clientId":"spongewallet-skill"}'
#122
#123	# Step 2: Poll for token
#124	curl -sS -X POST "https://api.wallet.paysponge.com/api/oauth/device/token" \
#125	-H "Sponge-Version: 0.2.2" \
#126	-H "Content-Type: application/json" \
#127	-d '{
#128	"grantType":"urn:ietf:params:oauth:grant-type:device_code",
#129	"deviceCode":"<deviceCode>",
#130	"clientId":"spongewallet-skill"
#131	}'
#132	```
#133
#134	### Standard Credential Storage
#135
#136	Store credentials in `~/.spongewallet/credentials.json`:
#137	```json
#138	{
#139	"apiKey": "sponge_live_...",
#140	"claimCode": "ABCD-1234",
#141	"claimUrl": "https://wallet.paysponge.com/device?code=ABCD-1234"
#142	}
#143	```
#144
#145	## Common Operations
#146
#147	### Check Balances
#148	```bash
#149	curl -sS "https://api.wallet.paysponge.com/api/balances?chain=base" \
#150	-H "Authorization: Bearer $SPONGE_API_KEY" \
#151	-H "Sponge-Version: 0.2.2"
#152	```
#153
#154	### Transfer USDC on Base
#155	```bash
#156	curl -sS -X POST "https://api.wallet.paysponge.com/api/transfers/evm" \
#157	-H "Authorization: Bearer $SPONGE_API_KEY" \
#158	-H "Sponge-Version: 0.2.2" \
#159	-H "Content-Type: application/json" \
#160	-d '{"chain":"base","to":"0x...","amount":"10","currency":"USDC"}'
#161	```
#162
#163	### Swap on Solana
#164	```bash
#165	curl -sS -X POST "https://api.wallet.paysponge.com/api/transactions/swap" \
#166	-H "Authorization: Bearer $SPONGE_API_KEY" \
#167	-H "Sponge-Version: 0.2.2" \
#168	-H "Content-Type: application/json" \
#169	-d '{"chain":"solana","inputToken":"SOL","outputToken":"USDC","amount":"0.1","slippageBps":50}'
#170	```
#171
#172	### Paid Services (3-Step Flow)
#173
#174	Step 1 — Find a service:
#175	```bash
#176	curl -sS "https://api.wallet.paysponge.com/api/discover?query=web+scraping" \
#177	-H "Authorization: Bearer $SPONGE_API_KEY" \
#178	-H "Sponge-Version: 0.2.2"
#179	```
#180
#181	Step 2 — Get service details (DO NOT SKIP):
#182	```bash
#183	curl -sS "https://api.wallet.paysponge.com/api/discover/{serviceId}" \
#184	-H "Authorization: Bearer $SPONGE_API_KEY" \
#185	-H "Sponge-Version: 0.2.2"
#186	```
#187
#188	Step 3 — Call the endpoint:
#189	```bash
#190	curl -sS -X POST "https://api.wallet.paysponge.com/api/paid/fetch" \
#191	-H "Authorization: Bearer $SPONGE_API_KEY" \
#192	-H "Sponge-Version: 0.2.2" \
#193	-H "Content-Type: application/json" \
#194	-d '{"url":"<url_from_step2>","method":"POST","body":{...},"chain":"base"}'
#195	```
#196
#197	### Bridge USDC to Hyperliquid for Trading
#198	```bash
#199	curl -sS -X POST "https://api.wallet.paysponge.com/api/transactions/bridge" \
#200	-H "Authorization: Bearer $SPONGE_API_KEY" \
#201	-H "Sponge-Version: 0.2.2" \
#202	-H "Content-Type: application/json" \
#203	-d '{"sourceChain":"base","destinationChain":"hyperliquid","token":"USDC","amount":"50"}'
#204	```
#205
#206	### Trade on Hyperliquid
#207	```bash
#208	curl -sS -X POST "https://api.wallet.paysponge.com/api/hyperliquid" \
#209	-H "Authorization: Bearer $SPONGE_API_KEY" \
#210	-H "Sponge-Version: 0.2.2" \
#211	-H "Content-Type: application/json" \
#212	-d '{"action":"order","symbol":"ETH","side":"buy","type":"limit","amount":"0.1","price":"3000"}'
#213	```
#214
#215	## Chain Reference
#216
#217	Supported chains: `ethereum`, `base`, `polygon`, `arbitrum-one`, `tempo`, `solana`
#218
#219	## Error Handling
#220
#221	\| Status \| Meaning \| Common Cause \|
#222	\|--------\|---------\|--------------\|
#223	\| 400 \| Bad Request \| Missing/invalid fields \|
#224	\| 401 \| Unauthorized \| Missing or invalid API key \|
#225	\| 403 \| Forbidden \| Permission denied \|
#226	\| 404 \| Not Found \| Resource does not exist \|
#227	\| 429 \| Rate Limited \| Too many requests \|
#228	\| 500 \| Server Error \| Transient; retry later \|
#229
#230	## Security
#231
#232	- Never share your API key in logs, posts, or screenshots
#233	- Store API key in environment variable `SPONGE_API_KEY`
#234	- Rotate the key if exposure is suspected
#235	- Use `sponge_test_` keys for development, `sponge_live_` for production
#236
#237	## Integration with Clawd
#238
#239	The Sponge Wallet can be used by Clawd in two ways:
#240
#241	1. Direct REST calls — use `fetch_url` tool or `curl` via shell to hit the Sponge API
#242	2. MCP Server — connect to `https://api.wallet.paysponge.com/mcp` with `Authorization: Bearer $SPONGE_API_KEY` header for structured tool access
#243

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public