pol-agents-sdk-demo
by @jameslawton
Complete Polygon agent toolkit. Session-based smart contract wallets (Sequence), token ops (send/swap/bridge/deposit via Trails), ERC-8004 on-chain identity...
clawhub install demo-agents-sdkπ About This Skill
name: polygon-agent-kit description: Complete Polygon agent toolkit. Session-based smart contract wallets (Sequence), token ops (send/swap/bridge/deposit via Trails), ERC-8004 on-chain identity + reputation, x402 micropayments. Single CLI entry point, AES-256-GCM encrypted storage.
Polygon Agent Kit
Prerequisites
npm install -g github:0xPolygon/polygon-agent-kitpolygon-agent ~/.polygon-agent/ (AES-256-GCM encrypted)Architecture
| Wallet | Created by | Purpose | Fund? |
|--------|-----------|---------|-------|
| EOA | setup | Auth with Sequence Builder | NO |
| Ecosystem Wallet | wallet create | Primary spending wallet | YES |
Environment Variables
Required
| Variable | When | |----------|------| |SEQUENCE_PROJECT_ACCESS_KEY | Wallet creation, swaps |
| SEQUENCE_INDEXER_ACCESS_KEY | Balance checks |Optional
| Variable | Default | |----------|---------| |SEQUENCE_ECOSYSTEM_CONNECTOR_URL | https://agentconnect.staging.polygon.technology/ |
| SEQUENCE_DAPP_ORIGIN | Same as connector URL origin |
| TRAILS_API_KEY | Falls back to SEQUENCE_PROJECT_ACCESS_KEY |
| TRAILS_TOKEN_MAP_JSON | Token-directory lookup |
| POLYGON_AGENT_DEBUG_FETCH | Off β logs HTTP to ~/.polygon-agent/fetch-debug.log |
| POLYGON_AGENT_DEBUG_FEE | Off β dumps fee options to stderr |Complete Setup Flow
# Phase 1: Setup (creates EOA + Sequence project, returns access key)
node cli/polygon-agent.mjs setup --name "MyAgent"
β save privateKey (not shown again), eoaAddress, accessKey
Phase 2: Create ecosystem wallet (auto-waits for browser approval)
export SEQUENCE_PROJECT_ACCESS_KEY=
node cli/polygon-agent.mjs wallet create --usdc-limit 100 --native-limit 5Phase 3: Fund wallet
node cli/polygon-agent.mjs fund
β opens Trails widget URL, fund via swap/bridge
Phase 4: Verify
export SEQUENCE_INDEXER_ACCESS_KEY=
node cli/polygon-agent.mjs balancesPhase 5: Register agent on-chain (ERC-8004, Polygon mainnet)
node cli/polygon-agent.mjs agent register --name "MyAgent" --broadcast
β mints ERC-721 NFT, emits agentId in Registered event
β use agentId for reputation queries and feedback
Commands Reference
Setup
polygon-agent setup --name [--force]
Wallet
polygon-agent wallet create [--name ] [--chain polygon] [--timeout ] [--no-wait]
[--native-limit ] [--usdc-limit ] [--usdt-limit ]
[--token-limit ] # repeatable
[--usdc-to --usdc-amount ] # one-off scoped transfer
[--contract ] # whitelist contract (repeatable)
polygon-agent wallet import --ciphertext '|@' [--name ] [--rid ]
polygon-agent wallet list
polygon-agent wallet address [--name ]
polygon-agent wallet remove [--name ]
Operations
polygon-agent balances [--wallet ] [--chain ]
polygon-agent send --to --amount [--symbol ] [--broadcast]
polygon-agent send-native --to --amount [--broadcast] [--direct]
polygon-agent send-token --symbol --to --amount [--broadcast]
polygon-agent swap --from --to --amount [--to-chain ] [--slippage ] [--broadcast]
polygon-agent deposit --asset --amount [--protocol aave|morpho] [--broadcast]
polygon-agent fund [--wallet ] [--token ]
polygon-agent x402-pay --url --wallet [--method GET] [--body ] [--header Key:Value]
Agent (ERC-8004)
polygon-agent agent register --name [--agent-uri ] [--metadata ] [--broadcast]
polygon-agent agent wallet --agent-id
polygon-agent agent metadata --agent-id --key
polygon-agent agent reputation --agent-id [--tag1 ]
polygon-agent agent reviews --agent-id
polygon-agent agent feedback --agent-id --value [--tag1 ] [--tag2 ] [--endpoint ] [--broadcast]
ERC-8004 contracts (Polygon mainnet):
0x8004A169FB4a3325136EB29fA0ceB6D2e539a4320x8004BAa17C55a88189AE136b182e5fdA19dE9b63Key Behaviors
--broadcast to execute--wallet main, --chain polygon, auto-wait on wallet createdeposit β picks highest-TVL pool via Trails getEarnPools. If session rejects, re-create wallet with --contract x402-pay β probes endpoint for 402, smart wallet funds builder EOA with exact token amount, EOA signs EIP-3009 payment. Chain auto-detected from 402 responsesend-native --direct β bypasses ValueForwarder contract for direct EOA transfer--usdc-limit etc., session gets bare-bones defaults and may not transactCRITICAL: Wallet Approval URL
When wallet create outputs a URL in the url or approvalUrl field, you MUST send the COMPLETE, UNTRUNCATED URL to the user. The URL contains cryptographic parameters (public key, callback token) that are required for session approval. If any part is cut off, the approval will fail.
... to the URLCallback Modes
The wallet create command automatically starts a local HTTP server and opens a Cloudflare Quick Tunnel (*.trycloudflare.com) β no account or token required. The cloudflared binary is auto-downloaded to ~/.polygon-agent/bin/cloudflared on first use if not already installed. The connector UI POSTs the encrypted session back through the tunnel regardless of where the agent is running. The tunnel and server are torn down automatically once the session is received.
Timing: The approvalUrl is only valid while the CLI process is running. Open it immediately and complete wallet approval within the timeout window (default 300s). Never reuse a URL from a previous run β the tunnel is torn down when the CLI exits.
Manual fallback (if cloudflared is unavailable): The CLI omits callbackUrl so the connector UI displays the encrypted blob in the browser. The CLI then prompts:
After approving in the browser, the encrypted blob will be shown.
Paste it below and press Enter:
>
The blob is also saved to /tmp/polygon-session-.txt for reference. To import later:
polygon-agent wallet import --ciphertext @/tmp/polygon-session-.txt
Troubleshooting
| Issue | Fix |
|-------|-----|
| Builder configured already | Add --force |
| Missing SEQUENCE_PROJECT_ACCESS_KEY | Run setup first |
| Missing wallet | wallet list, re-run wallet create |
| Session expired | Re-run wallet create (24h expiry) |
| Fee option errors | Set POLYGON_AGENT_DEBUG_FEE=1, ensure wallet has funds |
| Timed out waiting for callback | Add --timeout 600 |
| callbackMode: manual (no tunnel) | cloudflared unavailable β paste blob from browser when prompted; blob saved to /tmp/polygon-session- |
| 404 on *.trycloudflare.com | CLI timed out and tunnel is gone β re-run wallet create, open the new approvalUrl immediately |
| "Auto-send failed" in browser | Copy the ciphertext shown below that message; run wallet import --ciphertext ' |
| Deposit session rejected | Re-create wallet with --contract |
File Structure
~/.polygon-agent/
βββ .encryption-key # AES-256-GCM key (auto-generated, 0600)
βββ builder.json # EOA privateKey (encrypted), eoaAddress, accessKey, projectId
βββ wallets/.json # walletAddress, session, chainId, chain
βββ requests/.json # Pending wallet creation requests
βοΈ Configuration
polygon-agent setup --name [--force]
Wallet
polygon-agent wallet create [--name ] [--chain polygon] [--timeout ] [--no-wait]
[--native-limit ] [--usdc-limit ] [--usdt-limit ]
[--token-limit ] # repeatable
[--usdc-to --usdc-amount ] # one-off scoped transfer
[--contract ] # whitelist contract (repeatable)
polygon-agent wallet import --ciphertext '|@' [--name ] [--rid ]
polygon-agent wallet list
polygon-agent wallet address [--name ]
polygon-agent wallet remove [--name ]
Operations
polygon-agent balances [--wallet ] [--chain ]
polygon-agent send --to --amount [--symbol ] [--broadcast]
polygon-agent send-native --to --amount [--broadcast] [--direct]
polygon-agent send-token --symbol --to --amount [--broadcast]
polygon-agent swap --from --to --amount [--to-chain ] [--slippage ] [--broadcast]
polygon-agent deposit --asset --amount [--protocol aave|morpho] [--broadcast]
polygon-agent fund [--wallet ] [--token ]
polygon-agent x402-pay --url --wallet [--method GET] [--body ] [--header Key:Value]
Agent (ERC-8004)
polygon-agent agent register --name [--agent-uri ] [--metadata ] [--broadcast]
polygon-agent agent wallet --agent-id
polygon-agent agent metadata --agent-id --key
polygon-agent agent reputation --agent-id [--tag1 ]
polygon-agent agent reviews --agent-id
polygon-agent agent feedback --agent-id --value [--tag1 ] [--tag2 ] [--endpoint ] [--broadcast]
ERC-8004 contracts (Polygon mainnet):
0x8004A169FB4a3325136EB29fA0ceB6D2e539a4320x8004BAa17C55a88189AE136b182e5fdA19dE9b63π Tips & Best Practices
| Issue | Fix |
|-------|-----|
| Builder configured already | Add --force |
| Missing SEQUENCE_PROJECT_ACCESS_KEY | Run setup first |
| Missing wallet | wallet list, re-run wallet create |
| Session expired | Re-run wallet create (24h expiry) |
| Fee option errors | Set POLYGON_AGENT_DEBUG_FEE=1, ensure wallet has funds |
| Timed out waiting for callback | Add --timeout 600 |
| callbackMode: manual (no tunnel) | cloudflared unavailable β paste blob from browser when prompted; blob saved to /tmp/polygon-session- |
| 404 on *.trycloudflare.com | CLI timed out and tunnel is gone β re-run wallet create, open the new approvalUrl immediately |
| "Auto-send failed" in browser | Copy the ciphertext shown below that message; run wallet import --ciphertext ' |
| Deposit session rejected | Re-create wallet with --contract |