Skill: jameslawton/polygon-agents-sdk (version 1.0.0)

--- 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 - 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 | |----------|---------| | [REDACTED_SECRET] | `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 ```bash # 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 ```bash polygon-agent setup --name <name> [--force] ``` ### Wallet ```bash 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 ```bash 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) ```bash 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: [REDACTED_SECRET] - ReputationRegistry: [REDACTED_SECRET] ## 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 ```

path: QUICKSTART.md
content: ---
name: polygon-agent-kit-quickstart
description: Quick start guide for Polygon Agent Kit. Get project access key, create wallet with session permissions, register agent onchain, perform token operations. Context-efficient workflow for autonomous agents.
---

# Polygon Agent Kit - Quick Start

**Goal**: Zero to operational agent in 4 phases.

## Phase 1: Setup

```bash
polygon-agent setup --name "MyAgent"
```
Outputs `accessKey` — needed for all wallet operations. Save `privateKey` for backup.

---

## Phase 2: Create Wallet

```bash
export SEQUENCE_PROJECT_ACCESS_KEY=<access-key-from-phase-1>
```

`SEQUENCE_ECOSYSTEM_CONNECTOR_URL` defaults to `https://agentconnect.polygon.technology/` (the hosted connector). Override via env var to point at a local dev server or a different deployment.

### Option A: Auto-Wait (Default — zero copy/paste)
```bash
polygon-agent wallet create
```
The CLI automatically opens a **Cloudflare Quick Tunnel** (`*.trycloudflare.com`) and passes the callback URL to the connector UI. Open the URL in a browser → approve → the CLI receives the session automatically. Works whether the agent is local or remote. No account or token required — `cloudflared` is auto-downloaded to `~/.polygon-agent/bin/` on first use.

**CRITICAL**: The CLI outputs an `approvalUrl` that the user must open in a browser. You MUST send the COMPLETE, UNTRUNCATED URL to the user. Do NOT shorten it or add `...` — the URL contains cryptographic parameters that will break if truncated.

**IMPORTANT — open the URL immediately**: The approval link is only valid while the CLI process is running. The tunnel and 5-minute timeout start together. Do NOT reuse a URL from a previous run — if the CLI has already exited, the tunnel is gone and you will get a 404 from the cloudflared URL. Simply re-run `wallet create` to get a fresh URL.

**If cloudflared is unavailable** (`callbackMode: manual`): The browser will display the encrypted blob instead of posting it back. The CLI will prompt you to paste it:
```
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` automatically.

### Option B: Manual (explicit no-wait)
```bash
polygon-agent wallet create --no-wait
# Open output URL, approve, copy blob:
polygon-agent wallet import --ciphertext @/tmp/session.txt
```

### Session Permissions

Control what the session can do. Without these, the agent gets bare-bones defaults and may not be able to transact.

```bash
polygon-agent wallet create \
  --native-limit 5 \
  --usdc-limit 100 \
  --usdt-limit 50 \
  --token-limit WETH:0.5 \
  --contract 0xABAAd93EeE2a569cF0632f39B10A9f5D734777ca
```

| Flag | Purpose |
|------|---------|
| `--native-limit <amt>` | Max POL the session can spend |
| `--usdc-limit <amt>` | Max USDC the session can transfer |
| `--usdt-limit <amt>` | Max USDT the session can transfer |
| `--token-limit <SYM:amt>` | Max for any token by symbol (repeatable) |
| `--usdc-to <addr>` | Restrict USDC to this recipient (requires `--usdc-amount`) |
| `--usdc-amount <amt>` | USDC amount for `--usdc-to` recipient |
| `--contract <addr>` | Whitelist contract address (repeatable) |

**After approval**: Fund `walletAddress` with POL + tokens.

### Fund wallet via Trails
```bash
polygon-agent fund
```
Opens a Trails widget URL pre-filled with your wallet address. Open the URL in a browser to swap/bridge tokens into your wallet.

---

## Phase 3: Register Agent (ERC-8004)

```bash
polygon-agent agent register --name "MyAgent" --broadcast
```
Mints ERC-721 NFT with `agentId`. Check transaction for Registered event.

---

## Phase 4: Token Operations

```bash
# Balances
export SEQUENCE_INDEXER_ACCESS_KEY=<indexer-key>
polygon-agent balances

# Send POL (via ValueForwarder)
polygon-agent send --to 0x... --amount 1.0 --broadcast

# Send POL direct (bypass ValueForwarder)
polygon-agent send-native --to 0x... --amount 1.0 --broadcast --direct

# Send ERC20
polygon-agent send --symbol USDC --to 0x... --amount 10 --broadcast

# DEX Swap
polygon-agent swap --from USDC --to USDT --amount 5 --slippage 0.005 --broadcast
```

Omit `--broadcast` for dry-run preview.

---

## Commands Summary

| Command | Purpose |
|---------|---------|
| `setup` | Get project access key |
| `wallet create` | Create wallet (auto-waits for approval) |
| `wallet create --no-wait` | Generate session link (manual flow) |
| `wallet import` | Import encrypted session |
| `wallet list` | List configured wallets |
| `agent register` | Register agent onchain (ERC-8004) |
| `fund` | Open Trails widget to fund wallet |
| `balances` | Check token balances |
| `send [--symbol SYM]` | Send native or ERC20 |
| `send-native [--direct]` | Send POL/MATIC (explicit) |
| `send-token` | Send ERC20 by symbol (explicit) |
| `swap` | DEX swap via Trails |
| `agent wallet` | Get agent's payment wallet |
| `agent reputation` | Get agent reputation score |
| `agent feedback` | Submit on-chain feedback |
| `agent reviews` | Read all agent feedback |

**Smart defaults**: `--wallet main`, `--chain polygon`, `--name main`. Most commands need zero flags.

---

## Environment Variables

**Required**:
`SEQUENCE_PROJECT_ACCESS_KEY` (from setup), `SEQUENCE_INDEXER_ACCESS_KEY` (for balance checks)

**Defaults** (override if needed):
`SEQUENCE_ECOSYSTEM_CONNECTOR_URL` → `https://agentconnect.polygon.technology/`

**Optional**: `TRAILS_API_KEY`, `TRAILS_TOKEN_MAP_JSON`, `POLYGON_AGENT_DEBUG_FETCH=1`, `POLYGON_AGENT_DEBUG_FEE=1`

---

## Error Recovery

| Issue | Fix |
|-------|-----|
| Session expired | Re-run `wallet create` |
| Insufficient funds | Fund wallet address with POL |
| Fee errors | Set `POLYGON_AGENT_DEBUG_FEE=1` to inspect |
| Tx failed | Omit `--broadcast` for dry-run first |
| Callback timeout | `--timeout 600` |
| `callbackMode: manual` shown | cloudflared unavailable — paste blob from browser when prompted |
| 404 on `*.trycloudflare.com` URL | CLI timed out before you approved — re-run `wallet create` and open the new URL immediately |
| "Auto-send failed" in browser | Ciphertext is shown below the message — copy it and run `polygon-agent wallet import --ciphertext '<blob>'` |

---

## Storage

All credentials: `~/.polygon-agent/` (AES-256-GCM encrypted)

Repository: https://github.com/0xPolygon/polygon-agent-kit


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (MEDIUM)