pol-agents-sdk-demo

Complete Polygon agent toolkit. Session-based smart contract wallets (Sequence), token ops (send/swap/bridge/deposit via Trails), ERC-8004 on-chain identity...

Security Scan

The skill's requirements and runtime instructions are consistent with a Polygon agent/CLI workflow (session-based wallets, Sequence connector, Trails integration); nothing obvious is asking for unrelated credentials or actions, but this is an instruction-only skill so you should verify the external endpoints and binaries it instructs you to use before running anything.

Purpose & Capability

Name/description (Polygon agent toolkit) align with the declared env vars and instructions: Sequence access keys and an indexer key are reasonable for wallet creation, balance checks and swaps; Trails integration and cloudflared usage are consistent with the described functionality.

Instruction Scope

SKILL.md instructs the agent/user to create and store private keys, use SEQUENCE_* access keys, and to send untruncated approval URLs to the user. It also describes an automatic Cloudflare Quick Tunnel flow that posts encrypted session blobs to a connector UI. These actions are within the expected flow, but they involve transmitting encrypted session blobs and interacting with remote UIs (defaulting to a staging connector). Verify you are comfortable with the connector endpoint before proceeding.

Install Mechanism

The skill is instruction-only (no install spec), but the instructions tell users to 'npm install -g github:0xPolygon/polygon-agent-kit' and describe the CLI auto-downloading 'cloudflared' to ~/.polygon-agent/bin/. This is expected for the CLI workflow but means code/binaries will be fetched from external sources (GitHub and Cloudflare) when you follow the guide — verify repository and binary integrity.

Credentials

Requested environment variables (SEQUENCE_PROJECT_ACCESS_KEY, SEQUENCE_INDEXER_ACCESS_KEY, optional TRAILS_API_KEY, etc.) are appropriate for the claimed features. No unrelated secrets or broad system credentials are requested by the SKILL.md.

Persistence & Privilege

Skill is not always-included and uses the normal autonomous-invocation default. The instructions describe writing encrypted data to ~/.polygon-agent/ and temporary session files in /tmp — this is expected for a CLI wallet tool and the skill does not request elevated or cross-skill privileges.

Assessment

This skill is an instruction-only guide for a CLI that manages Polygon wallets and sessions; it appears internally consistent but exercises care is required before running the recommended commands. Things to consider before installing/using it: - The setup creates private keys and access keys (SEQUENCE_PROJECT_ACCESS_KEY). Treat those like secrets: do not paste them into chat or public logs, and back up private keys securely. - The default connector URL in the docs is a staging host (agentconnect.staging.polygon.technology). Confirm you want to use the staging connector or switch to a trusted production endpoint before creating sessions — sessions and approval callbacks are sent to that connector/UI. - The CLI will (per docs) auto-download the cloudflared binary into ~/.polygon-agent/bin/. If you run the CLI, verify the source and integrity of downloaded binaries (or install cloudflared yourself from Cloudflare before running) to reduce supply-chain risk. - The flow requires you to open an untruncated approval URL (it contains cryptographic parameters). Only open such links in a trusted browser and only when you initiated the flow; do not share approval URLs or session blobs with untrusted parties. - The SKILL.md points to a GitHub repo (0xPolygon/polygon-agent-kit). If you plan to install the CLI, review the repository and recent commits to confirm the code matches your expectations. - If you want lower risk during experimentation, use manual/no-wait flows and dry-run mode (omit --broadcast) rather than automatic approval/tunnel flows that post to remote UIs. If you want, I can list the exact lines in SKILL.md that reference external endpoints, binary downloads, or sensitive outputs so you can review them before proceeding.

Polygon Agent Kit

Prerequisites

• Node.js 20+
• Install globally: npm install -g github:0xPolygon/polygon-agent-kit
• Entry point: polygon-agent <command>
• Storage: ~/.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=<accessKey>
node cli/polygon-agent.mjs wallet create --usdc-limit 100 --native-limit 5

# Phase 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=<indexerKey>
node cli/polygon-agent.mjs balances

# Phase 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 <name> [--force]

Wallet

polygon-agent wallet create [--name <n>] [--chain polygon] [--timeout <sec>] [--no-wait]
  [--native-limit <amt>] [--usdc-limit <amt>] [--usdt-limit <amt>]
  [--token-limit <SYM:amt>]  # repeatable
  [--usdc-to <addr> --usdc-amount <amt>]  # one-off scoped transfer
  [--contract <addr>]  # whitelist contract (repeatable)
polygon-agent wallet import --ciphertext '<blob>|@<file>' [--name <n>] [--rid <rid>]
polygon-agent wallet list
polygon-agent wallet address [--name <n>]
polygon-agent wallet remove [--name <n>]

Operations

polygon-agent balances [--wallet <n>] [--chain <chain>]
polygon-agent send --to <addr> --amount <num> [--symbol <SYM>] [--broadcast]
polygon-agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
polygon-agent send-token --symbol <SYM> --to <addr> --amount <num> [--broadcast]
polygon-agent swap --from <SYM> --to <SYM> --amount <num> [--to-chain <chain>] [--slippage <num>] [--broadcast]
polygon-agent deposit --asset <SYM> --amount <num> [--protocol aave|morpho] [--broadcast]
polygon-agent fund [--wallet <n>] [--token <addr>]
polygon-agent x402-pay --url <url> --wallet <n> [--method GET] [--body <str>] [--header Key:Value]

Agent (ERC-8004)

polygon-agent agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast]
polygon-agent agent wallet --agent-id <id>
polygon-agent agent metadata --agent-id <id> --key <key>
polygon-agent agent reputation --agent-id <id> [--tag1 <tag>]
polygon-agent agent reviews --agent-id <id>
polygon-agent agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--broadcast]

ERC-8004 contracts (Polygon mainnet):

• IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

Key Behaviors

• Dry-run by default — all write commands require --broadcast to execute
• Smart defaults — --wallet main, --chain polygon, auto-wait on wallet create
• Fee preference — auto-selects USDC over native POL when both available
• deposit — picks highest-TVL pool via Trails getEarnPools. If session rejects, re-create wallet with --contract <depositAddress>
• 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 response
• send-native --direct — bypasses ValueForwarder contract for direct EOA transfer
• Session permissions — without --usdc-limit etc., session gets bare-bones defaults and may not transact

CRITICAL: 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.

• Do NOT shorten, summarize, or add ... to the URL
• Do NOT split the URL across multiple messages
• Output the raw URL exactly as returned by the CLI

Callback 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:
> <paste blob here>

The blob is also saved to /tmp/polygon-session-<rid>.txt for reference. To import later:

polygon-agent wallet import --ciphertext @/tmp/polygon-session-<rid>.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-<rid>.txt
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 '<blob>'
Deposit session rejected	Re-create wallet with --contract <depositAddress>

File Structure

~/.polygon-agent/
├── .encryption-key       # AES-256-GCM key (auto-generated, 0600)
├── builder.json          # EOA privateKey (encrypted), eoaAddress, accessKey, projectId
├── wallets/<name>.json   # walletAddress, session, chainId, chain
└── requests/<rid>.json   # Pending wallet creation requests