Polygon Agent

Polygon エージェント CLI

前提条件

• Node.js 20 以上
• グローバルインストール: npm install -g @polygonlabs/agent-cli（更新するには再インストール）
• エントリポイント: polygon-agent <command>
• 保存場所: ~/.polygon-agent/（AES-256-GCM 暗号化）

エージェント向けの注意: 初回インストール時には、これがグローバルの npm インストールであることをユーザーに伝えてください — polygon-agent CLI をシステム全体にインストールするため、どのターミナルからでも実行でき、環境によっては sudo が必要になる場合があり、同じコマンドを再実行すると更新され、npm uninstall -g @polygonlabs/agent-cli で削除できます。初回インストール時に一度だけ言及してください。

コマンドが「Unknown argument」または「command not found」で失敗する場合

このスキルは CLI とともにバージョン管理されています — コマンドとフラグはリリースごとに変動します。自分のバージョンを確認し、最新版と比較して、遅れている場合はアップグレードしてください:

polygon-agent --version                        # currently installed
npm view @polygonlabs/agent-cli version        # latest published
npm install -g @polygonlabs/agent-cli@latest   # upgrade

アーキテクチャ

ウォレット	作成元	目的	資金供給?
EOA	setup	Sequence Builder での認証	いいえ
エコシステムウォレット	wallet create	主要な支払い用ウォレット	はい

環境変数

アクセスキー — 1 つのキー、多くの名前

SEQUENCE_PROJECT_ACCESS_KEY、SEQUENCE_INDEXER_ACCESS_KEY、TRAILS_API_KEY はすべて同じキーです — setup 中に作成される Sequence プロジェクトのアクセスキーです。CLI はこれらをエイリアスとして扱い、すべてを自動的にフォールバックします。

setup の実行後、キーは ~/.polygon-agent/builder.json に保存されます。CLI の呼び出しごとにこれを環境にブートストラップするため、export は不要です。環境変数が何も設定されていない新しいエージェントセッションでは、単にコマンドを実行するだけで、CLI はディスクから認証情報を読み取ります。

保存された値を上書きする場合にのみ、これらを手動で設定してください（たとえば、別のプロジェクトを指定する場合）:

export SEQUENCE_PROJECT_ACCESS_KEY=<key>  # also covers TRAILS_API_KEY and indexer calls

オプションの上書き

変数	デフォルト
SEQUENCE_ECOSYSTEM_CONNECTOR_URL	https://agentconnect.polygon.technology
SEQUENCE_DAPP_ORIGIN	コネクター URL のオリジンと同じ
TRAILS_TOKEN_MAP_JSON	トークンディレクトリのルックアップ
POLYGON_AGENT_DEBUG_FETCH	オフ — HTTP を ~/.polygon-agent/fetch-debug.log に記録します
POLYGON_AGENT_DEBUG_FEE	オフ — 手数料オプションを stderr にダンプします

完全なセットアップフロー

# Step 1: Setup (creates EOA + Sequence project, stores access key to disk)
polygon-agent setup --name "MyAgent"
# → saves privateKey (not shown again), eoaAddress, accessKey to ~/.polygon-agent/builder.json
# → all subsequent commands auto-load the access key from disk — no export needed

# Step 2: Create ecosystem wallet (opens browser, waits for 6-digit code)
# Aave V3 Pool is auto-whitelisted in all sessions. For Morpho or other DeFi vaults,
# add --contract flags as needed.
polygon-agent wallet create --usdc-limit 50 --native-limit 5 \
  --contract 0xc2132D05D31c914a87C6611C10748AEb04B58e8F \
  --contract 0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619 \
  --contract 0x781fb7f6d845e3be129289833b04d43aa8558c42 \
  --contract 0xf5c81d25ee174d83f1fd202ca94ae6070d073ccf \
  --contract 0x3f33f9f7e2d7cfbcbdf8ea8b870a6e3d449664c2
# → opens https://agentconnect.polygon.technology/link?rid=<rid>&...
# → user approves in browser, browser shows a 6-digit code
# → enter the 6-digit code in the terminal when prompted
# → session saved to ~/.polygon-agent/wallets/main.json
# → notify the user and send them to https://agentconnect.polygon.technology/?rid=<rid>
#   so they can fund their wallet with access to the session

# Step 3: Fund wallet
polygon-agent 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

# Step 4: Verify balances
polygon-agent balances

# Step 5: Register agent on-chain (ERC-8004, Polygon mainnet only)
polygon-agent agent register --name "MyAgent" --broadcast
# → mints ERC-721 NFT, emits Registered event containing agentId
# → retrieve agentId: open the tx on https://polygonscan.com, go to Logs tab,
#   find the Registered event — agentId is the first indexed parameter
# → use agentId for reputation queries, reviews, and feedback

ユースケース別スキル

特定のワークフローについては、タスクを試みる前に関連するサブスキルを取得して読み込んでください:

ユースケース	スキル URL
Polymarket 予測市場の取引	https://agentconnect.polygon.technology/polygon-polymarket/SKILL.md
DeFi — スワップ、入金、出金、イールド	https://agentconnect.polygon.technology/polygon-defi/SKILL.md
x402 の検出と従量課金 API	https://agentconnect.polygon.technology/polygon-discovery/SKILL.md

重要 — x402 呼び出し: ユーザーが x402 を使ってデータ（Twitter/X のプロフィール、ウェブ検索、ニュース、AI 画像、コードレビューなど）を取得したいと依頼した場合は、リクエストを行う前に次の手順を順番に実行してください:

1. ディスカバリースキルを取得して読む: GET https://agentconnect.polygon.technology/polygon-discovery/SKILL.md
2. polygon-agent wallet list を実行する — ウォレットが存在しない場合は、ウォレット作成フローを実行します: polygon-agent setup（まだ実行していない場合）、続いて polygon-agent wallet create を実行してブラウザセッションを開き、安全な暗号化ウォレットセッションを確立します。プロンプトが表示されたら 6 桁のコードを入力し、続行する前にウォレットに資金を供給します。
3. polygon-agent balances を実行する — 続行する前に USDC が利用可能であることを確認します。ウォレットが空の場合、x402 呼び出しは EOA の資金供給エラーで失敗します

エンドポイントを推測したり、x402 プロバイダーをウェブで検索したりしないでください。ディスカバリースキルには、正確な URL 形式で、正しく動作するエンドポイントが記載されています。

---

コマンドリファレンス

セットアップ

polygon-agent setup --name <name> [--force]

ウォレット

有効な --chain の値: polygon（デフォルト/メインネット）、amoy（Polygon テストネット）、mainnet（Ethereum）、arbitrum、optimism、base。ERC-8004 エージェント操作は polygon のみをサポートします。

polygon-agent wallet create [--name <n>] [--chain polygon] [--timeout <sec>] [--print-url]
  [--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 --code <6-digit-code> --rid <rid> [--name <n>]
polygon-agent wallet import --ciphertext '<blob>|@<file>' [--name <n>]  # legacy
polygon-agent wallet list
polygon-agent wallet address [--name <n>]
polygon-agent wallet remove [--name <n>]

操作

polygon-agent balances [--wallet <n>] [--chain <chain>] [--chains <csv>]
polygon-agent send --to <addr> --amount <num> [--symbol <SYM>] [--token <addr>] [--decimals <n>] [--broadcast]
polygon-agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
polygon-agent send-token --symbol <SYM> --to <addr> --amount <num> [--token <addr>] [--decimals <n>] [--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 withdraw --position <addr> --amount <num|max> [--chain <chain>] [--broadcast]
polygon-agent fund [--wallet <n>] [--token <addr>]
polygon-agent x402-pay --url <url> --wallet <n> [--method GET] [--body <str>] [--header Key:Value]

エージェント (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>] [--tag2 <tag>]
polygon-agent agent reviews --agent-id <id> [--tag1 <t>] [--tag2 <t>] [--revoked]
polygon-agent agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--feedback-uri <uri>] [--broadcast]

ERC-8004 コントラクト (Polygon メインネット):

• IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

主な動作

• デフォルトでドライラン — すべての書き込みコマンドは実行に --broadcast が必要です
• スマートデフォルト — --wallet main、--chain polygon、wallet create では自動待機
• balances --chains — カンマ区切りのチェーン (最大 20)。2 つ以上を指定すると multiChain: true と chains 配列を含む JSON を返します (各チェーンで同じウォレットアドレス)
• 手数料の優先設定 — USDC とネイティブ POL の両方が利用可能な場合は USDC を自動選択します
• fund — fundingUrl として https://wallet.polygon.technology を返します。URL とウォレットアドレスを取得するには必ず polygon-agent fund を実行してください — ハードコードしたり手動で構築したりしないでください。
• deposit — Trails の getEarnPools を介して TVL が最も高いプールを選択し、直接デポジットします。Aave V3 Pool (0x794a61358d6845594f94dc1db02a252b5b4814ad) はすべてのセッションで自動的にホワイトリスト登録されます。デポジットの完全なリファレンス: https://agentconnect.polygon.technology/polygon-defi/SKILL.md
• ガスリザーブ — deposit やトークンを消費する任意のコマンドを使用する場合、ガス用にウォレットに少なくとも 0.1 USDC または 0.1 POL を常に確保してください。残高全体を使い切ろうとしないでください。deposit コマンドは 0.1 のリザーブを自動的に適用しますが、send、swap、または直接のコントラクト呼び出しの金額を構築する際には、エージェントが同じルールを適用する必要があります。
• withdraw — --position = aToken または ERC-4626 ボールト、--amount = max または基盤となる単位 (Aave / ボールト)。ドライラン JSON には poolAddress / vault が含まれます。ブロードキャストには --chain と同じチェーン上のセッションが必要で、リレイヤーがそれらに触れる場所でプール/ボールト + 基盤トークンがホワイトリスト登録されている必要があります
• x402-pay — エンドポイントをプローブして 402 を確認し、スマートウォレットがビルダー EOA に正確なトークン量を入金し、EOA が EIP-3009 支払いに署名します。チェーンは 402 レスポンスから自動検出されます
• send-native --direct — 直接 EOA 転送のために ValueForwarder コントラクトをバイパスします
• セッション権限 — --usdc-limit などを指定しない場合、セッションは最小限のデフォルトを受け取り、トランザクションを実行できない場合があります
• セッションの有効期限 — 作成から 6 か月
• ワンパスでのセッションセットアップ — ユーザーの意図に DeFi (デポジット、イールド、スワップ、Aave、Morpho) が含まれる場合は、追加のコントラクト (Morpho ボールトなど) を最初の wallet create 呼び出しに含めてください。素のセッションを作成してから、後でデポジットを試みるときにユーザーに再承認を求めることは決してしないでください。

ウォレット作成フロー (v2 リレー)

wallet create は Cloudflare Durable Object リレーと 6 桁のアウトオブバンドコードを使用します — cloudflared トンネルは不要です。ブラウザはリレーを介してネゴシエートされた X25519 鍵で承認済みセッションを暗号化します。6 桁のコードはターミナルで入力する復号鍵です。

--print-url フラグ: wallet create がコードを待ってブロックできないヘッドレスまたは非対話環境 (CI、リモートシェル) で使用してください。CLI は承認 URL を出力して即座に終了します。フローは別途完了させてください:

polygon-agent wallet import --code <6-digit-code> --rid <rid>

重要: ウォレット承認 URL

wallet create が url または approvalUrl フィールドに URL を出力した場合、完全で切り詰められていない URL をユーザーに送信してください。この URL にはセッション承認に必要なリレーリクエスト ID が含まれています。

• URL を短縮したり、要約したり、... を追加したりしないでください
• URL を複数のメッセージに分割しないでください
• CLI が返したとおりの生の URL をそのまま出力してください

ユーザーへの結果の提示

CLI コマンドは JSON を出力します（非 TTY）。コマンドを実行した後は、必ず結果を整形された Markdown としてレンダリングしてください — 生の JSON を会話に貼り付けないでください。

コマンド	提示方法
balances	Markdown テーブル: Token / Balance 列。テーブルの上にウォレットアドレスとチェーンを表示します。
send / send-token / send-native	一行サマリー: 金額、シンボル、受取人。ブロードキャストした場合は、tx ハッシュをコードスパンとして、エクスプローラー URL をリンクとして表示します。
swap	サマリー: チェーン付きで X FROM → Y TO。ブロードキャストした場合は、deposit tx ハッシュ + エクスプローラーリンクを表示します。
deposit	サマリー: 金額、アセット、プロトコル、プールアドレス。ブロードキャストした場合は、tx ハッシュ + エクスプローラーリンクを表示します。
withdraw	サマリー: kind（aave / erc4626）、ポジション、金額、プールまたはボールト。ブロードキャストした場合は、tx ハッシュ + エクスプローラーリンクを表示します。
fund	fundingUrl をクリック可能なリンクとして表示し、開くための簡単な手順を添えます。
wallet create / wallet list	ウォレット名、短縮アドレス、チェーンを小さなテーブルまたは箇条書きで表示します。
agent register	エージェント名と tx ハッシュをコードスパンとして表示し、Polygonscan リンクを添えます。Logs タブの Registered イベントから agentId を取得するようユーザーに促します。
agent wallet	agentId、ウォレットアドレス、ウォレットが設定されているかどうかを表示します。
agent metadata	agentId、キー、デコードされた値を表示します。
agent reputation	スコアとタグの内訳を小さなテーブルとして整形します。

ドライランの結果 — これがシミュレーションであることを常に視覚的に明確にしてください。⚡ Dry run を先頭に付け、何が起こるはずかを表示します。実行するには --broadcast を付けて再実行するようユーザーに促します。

エラー — error フィールドを抽出し、JSON の塊ではなく明確な文として提示します。該当する場合は、トラブルシューティング表から関連する修正方法を含めます。

---

トラブルシューティング

問題	修正方法
Builder configured already	--force を追加します
Missing SEQUENCE_PROJECT_ACCESS_KEY	先に setup を実行します
Missing wallet	wallet list を実行し、wallet create を再実行します
Session expired	wallet create を再実行します（6 か月で期限切れ）
Fee option errors	POLYGON_AGENT_DEBUG_FEE=1 を設定し、ウォレットに資金があることを確認します
Timed out waiting for wallet approval	--timeout 600 を追加します
Invalid code: hash mismatch	誤った 6 桁のコードが入力されました — 再試行します（3 回まで許可）
Relay request not found	セッションが期限切れか、すでに使用済みです — wallet create を再実行します（または wallet create --print-url）
Deposit session rejected	--contract <tokenAddress> --contract <depositAddress> を付けてウォレットを再作成します（両方必須: token approve + pool call）
withdraw / ブロードキャスト: チェーンが違う、またはセッションが拒否する	wallet create --chain <same as --chain> を使用し、そのチェーン上のプール/ボールト + 基盤となる ERC-20 に対して --contract を指定します。手数料の転送を妨げる場合は厳しい --usdc-limit を省略します
Stored explicit session is missing pk	再リンクします: wallet create の後に wallet import --code … を実行します
Trails ウィジェットで受取人が間違っている	polygon-agent fund を実行します（URL を手動で構築しないでください）
x402-pay: 402 レスポンスがない	エンドポイントが x402 支払いを必要としていないか、URL が間違っています
x402-pay: 支払いトークンの不一致	402 レスポンスのチェーン/トークンがウォレットと異なります — --wallet が正しいチェーンを指しているか確認します
x402-pay: EOA の資金調達に失敗	ウォレットに支払い金額をカバーする十分な残高がありません — balances を実行し、必要に応じて資金を追加します

ファイル構造

~/.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 (deleted after successful import)