Polygon Agents SDK

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 instructions and required secrets align with a Polygon wallet/agent CLI, but it asks the agent/user to perform sensitive actions (auto-download/run a tunnel binary, open public callback URLs, write private keys to disk and /tmp) without inline verification and the registry metadata lacks a verifiable homepage — review the code and binary sources before installing.

Purpose & Capability

Name, description, and the CLI commands in SKILL.md consistently describe a Polygon agent toolkit (wallet/session creation, token ops, ERC‑8004 registration). The declared environment variables in the docs (SEQUENCE_PROJECT_ACCESS_KEY, SEQUENCE_INDEXER_ACCESS_KEY, optional Trails keys) are appropriate for the described functionality.

Instruction Scope

The instructions require running a third‑party CLI (npm install -g github:0xPolygon/polygon-agent-kit) that will: create and store private keys, auto-open a Cloudflare Quick Tunnel, save session blobs to /tmp, and insist you transmit full approval URLs to users. Those actions are expected for a session-based wallet flow, but they broaden the agent's runtime surface (network-exposed tunnels, temporary plaintext blobs, local storage of private keys) and could enable attack vectors if the underlying code or downloaded binaries are malicious or tampered with.

Install Mechanism

SKILL.md instructs installation from a GitHub repo via npm (github:0xPolygon/polygon-agent-kit) — a common pattern but still fetches code at install time. More concerning: the CLI auto-downloads a cloudflared binary into ~/.polygon-agent/bin/ on first use. Auto-downloading and executing binaries from the network increases risk unless the source and integrity checks (signatures/checksums) are explicit. The registry metadata itself had no install spec or homepage listed, which reduces traceability.

Credentials

Required environment variables listed in SKILL.md (SEQUENCE_PROJECT_ACCESS_KEY and SEQUENCE_INDEXER_ACCESS_KEY) are directly relevant to wallet/session operations. Optional vars (TRAILS_API_KEY, TRAILS_TOKEN_MAP_JSON, debug flags) also make sense. The skill will output and ask you to save private keys and stores encrypted material in ~/.polygon-agent/ — expected, but these are high‑sensitivity secrets and the workflow involves temporary plaintext blobs in /tmp and URLs that must be copied exactly.

Persistence & Privilege

The skill is instruction-only and does not request always:true or other elevated platform privileges. However, the CLI behavior described will create persistent files under ~/.polygon-agent/ (encrypted storage and a bin folder for cloudflared) and write temporary files under /tmp; it also spawns a network tunnel. Those are normal for a CLI wallet but constitute persistent disk and network state that you should be willing to host on the machine used.

Scan Findings in Context

[no-regex-findings] expected: The scanner found no code files to analyze (the skill is instruction-only). This is expected given the package is not embedded in the registry entry — it directs users to install a GitHub-hosted npm package instead. Absence of findings does not mean the upstream package or auto-downloaded binaries are safe.

What to consider before installing

This skill appears to implement what it claims, but it performs sensitive operations (generates/saves private keys, auto-downloads/executes cloudflared, exposes a public tunnel and temporary blobs). Before installing or running it: 1) Verify the upstream repo (https://github.com/0xPolygon/polygon-agent-kit) is authentic and review its code — especially any cloudflared download logic and where binaries are fetched from. 2) Prefer installing and running in an isolated environment (VM/container) rather than a primary machine. 3) Do not paste or share private keys or session blobs publicly; treat SEQUENCE_* keys as secrets. 4) If you must use it on a workstation, verify any downloaded binary checksums/signatures and consider using your own Cloudflare/connector setup instead of auto-tunnel. 5) If you lack comfort auditing the code, ask for a signed release or a package from a verifiable publisher 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.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
# → reads walletAddress from session, builds Trails widget URL with toAddress=<walletAddress>
# → ALWAYS run this command to get the URL — never construct it manually or hardcode any address
# → send the returned `fundingUrl` to the user; `walletAddress` in the output confirms the recipient

# 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
• fund — reads walletAddress from the wallet session and sets it as toAddress in the Trails widget URL. Always run polygon-agent fund to get the correct URL — never construct it manually or hardcode any address. The returned JSON contains fundingUrl and walletAddress so you can confirm the pre-filled recipient before sharing.
• 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>
Wrong recipient in Trails widget	Run polygon-agent fund (do not construct the URL manually); walletAddress in the output confirms the pre-filled toAddress

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