polygon-agent-cli

Polygon Agentic CLI

前提条件

• Node.js 22+
• グローバルにインストール: npm install -g @polygonlabs/agent-cli (更新するには再インストール)
• エントリポイント: agent <command>
• ストレージ: ~/.polygon-agent/ (AES-256-GCM で暗号化)

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

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

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

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

アーキテクチャ

CLI は OMS (Open Money Stack) V3 埋め込みウォレットモデル (@polygonlabs/oms-wallet) を使用します。デフォルトでは、wallet login は agentconnect ログインページ (POLYGON_AGENT_LOGIN_UI、デフォルト https://agentconnect.polygon.technology) を開き、そこでユーザーは Google またはメールを選択します (メールはユーザーの受信トレイに 6 桁のコードを送信し、ページに入力します)。これはブラウザがこのマシン上にあるか別のマシン上にあるかに関係なく機能するため、別個のヘッドレスモードはありません。--local は従来のループバックフロー (生の Google サインイン URL と localhost コールバック。ブラウザはこの同じマシン上にある必要があり、Google のみ) にフォールバックします。--remote は非推奨であり、現在は通知を出力するだけの no-op です。ユーザーがサインインすると、ウォレットが作成またはロック解除され、セッション資格情報が暗号化されてディスクに保存されます。オンチェーンの権限スコープはありません。

ウォレット	作成者	目的	資金供給?
埋め込みウォレット (V3)	wallet login	主要な支払い用ウォレット	はい

ウォレットアドレスはすべての EVM チェーンで同じです。セッションは再ログインが必要になるまで約 1 週間持続します。

環境変数

OMS 資格情報 (オプション)

セットアップ手順は必要ありません。CLI にはデフォルトの OMS 公開可能キーが同梱されており、wallet login は初回ログイン時に専用の Builder プロジェクトとアクセスキーを自動的にプロビジョニングし、~/.polygon-agent/builder.json に保存します。

変数	説明
OMS_PUBLISHABLE_KEY	高度な上書き: デフォルトの代わりに独自の OMS Builder プロジェクトを指定します

env で設定するか、setup で一度永続化すると、すべてのコマンドが ~/.polygon-agent/builder.json から読み取ります:

agent setup --oms-publishable-key <key>

--oms-project-id <proj_...> も受け付けられますがオプションです — これはレガシーな表示メタデータとしてのみ保持されています。プレーンな setup (キーなし) は、手動または --force での再プロビジョニングでも引き続き機能します。

オプションの上書き

変数	デフォルト
POLYGON_AGENT_LOGIN_UI	wallet login が開くブラウザログインページのベース URL (デフォルト https://agentconnect.polygon.technology)
POLYGON_AGENT_OIDC_RELAY	wallet login が使用する OIDC リレーのベース URL (デフォルト https://oidc-relay.polygon.technology)。実行ごとに --relay-url でも設定可能
SEQUENCE_PROJECT_ACCESS_KEY	DeFi のアーンポリシールックアップ用の Trails API キーとしてのみ使用されます (オプション)
TRAILS_TOKEN_MAP_JSON	トークンディレクトリのルックアップ
POLYGON_AGENT_DEBUG_FETCH	オフ — HTTP を ~/.polygon-agent/fetch-debug.log にログ出力します
POLYGON_AGENT_DEBUG_FEE	オフ — 手数料オプションを stderr にダンプします

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

# Step 1: Log in in the browser
agent wallet login
# → opens the agentconnect login page; choose Google or email (email sends
#   a 6-digit code to the user's inbox, entered on the page)
# → works whether the browser is on this machine or elsewhere, so there is
#   no separate headless mode
# → --local falls back to the legacy loopback flow (Google only, browser
#   must be on this machine)
# → session saved to ~/.polygon-agent/oms/main/; prints the walletAddress
# → no setup step needed: the CLI ships a default OMS publishable key, and
#   login auto-provisions a Builder project + access key to
#   ~/.polygon-agent/builder.json

# Step 1b: Choose transaction mode (asked once)
# → if the login output includes a `modePrompt` field, ask the user whether to
#   enable auto mode (writes broadcast immediately, no preview), then run:
agent mode auto      # or: agent mode dry-run
# → dry-run (default) previews every write; auto broadcasts immediately.
#   Never enable auto mode without the user's explicit answer.

# Step 2: Fund wallet
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 3: Verify balances
agent balances

# Step 4: Register agent on-chain (ERC-8004, Polygon mainnet only)
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
スワップ、ブリッジ & デポジット（イールド引き出しも含む）	https://agentconnect.polygon.technology/polygon-defi/SKILL.md
x402 ディスカバリー & 従量課金 API	https://agentconnect.polygon.technology/polygon-discovery/SKILL.md

IMPORTANT — x402 呼び出し： ユーザーが x402 を使ってデータを取得したり、サービス（ウェブ検索、スクレイピング、ニュース、LLM 推論、メール、オンチェーンウォレット分析、マルチチェーン RPC など）を呼び出したりするよう求めた場合は、リクエストを行う前に次の手順を順番に実行してください：

1. ディスカバリースキルを取得して読む：GET https://agentconnect.polygon.technology/polygon-discovery/SKILL.md
2. agent wallet list を実行する — ウォレットが存在しない場合はログインします：agent wallet login を実行し、ログインページでサインイン（Google またはメール）してから、続行する前にウォレットに入金してください。事前のセットアップ手順は不要です。
3. agent balances を実行する — 続行する前に USDC が利用可能であることを確認してください。ウォレットが空の場合、x402 呼び出しは EOA の資金エラーで失敗します

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

---

コマンドリファレンス

セットアップ

agent setup [--name <name>] [--force]
  [--oms-publishable-key <key>] [--oms-project-id <proj_...>]  # save OMS credentials (project id optional/legacy)
agent mode [auto|dry-run]   # show or set the persisted transaction mode

ウォレット

操作で有効な --chain の値：polygon（デフォルト/メインネット）、amoy（Polygon テストネット）、mainnet（Ethereum）、arbitrum、optimism、base。ERC-8004 エージェント操作は polygon のみをサポートします。組み込みウォレットのアドレスはすべてのチェーンで同じです。

agent wallet login [--name <n>] [--local] [--no-fund] [--force]
# Opens the agentconnect login page; choose Google or email. Works whether the browser is local or remote, so there is no separate headless mode.
# --local falls back to the legacy loopback flow (raw Google URL + localhost callback; browser must be on this machine; Google only). --remote is deprecated (now a no-op with a notice).
agent wallet logout [--name <n>]   # clears the local session
agent wallet list
agent wallet address [--name <n>]
agent wallet remove [--name <n>]

操作

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

すべての書き込みコマンドは --broadcast（実行）と --dry-run（強制的にプレビュー）を受け付けます。どちらも指定しない場合は、永続化された agent mode が決定します。

エージェントのアイデンティティ & レピュテーション（ERC-8004）

agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast|--dry-run]
agent identity --agent-id <id> [--key <metadata-key>]   # agent payment wallet + optional metadata
agent reputation --agent-id <id> [--tag1 <tag>] [--tag2 <tag>]
agent reviews --agent-id <id> [--tag1 <t>] [--tag2 <t>] [--include-revoked]
agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--feedback-uri <uri>] [--broadcast|--dry-run]

ERC-8004 コントラクト（Polygon メインネット）：

• IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

主な動作

• トランザクションモード — デフォルトの dry-run モードでは、書き込みコマンドは実行内容をプレビューし、実行には --broadcast が必要です。agent mode auto を実行すると、常にブロードキャストする設定が保存されます。どのコマンドでも --dry-run を指定すると、モードに関係なくプレビューが表示されます。最初の wallet login の後、ログイン JSON に modePrompt フィールドが含まれている場合は、その質問をユーザーに伝え、回答に応じて agent mode auto または agent mode dry-run を実行してから続行してください。ユーザーの明示的な回答なしに、自動モードを有効にしてはいけません。
• スマートデフォルト — --wallet main、--chain polygon
• balances --chains — カンマ区切りのチェーン（最大20件）を指定します。2件以上を指定すると、multiChain: true と chains 配列を含む JSON が返されます（各チェーンで同じウォレットアドレスを使用します）。
• 手数料の優先設定 — USDC とネイティブ POL の両方を利用できる場合は、USDC を自動選択します。リレイヤーは、ウォレットが支払える手数料トークンでガス代を支払います。
• fund — ウォレットとチェーンがあらかじめ入力された agentconnect ダッシュボードの入金 URL を fundingUrl として返します。URL とウォレットアドレスを取得するには、必ず agent fund を実行してください。手動でハードコードしたり、組み立てたりしてはいけません。
• deposit — Trails の getEarnPools を使って TVL が最も高いプールを選び、直接入金します。入金の詳細については、以下を参照してください：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／ボールト）を指定します。dry-run の JSON には poolAddress／vault が含まれます。
• x402-pay — エンドポイントに 402 が返るか確認し、デフォルトで選択された支払い内容をプレビューします。自動モードまたは --broadcast の場合、ウォレットから正確なトークン額をビルダー EOA に送金して、支払いを完了します。チェーンは 402 レスポンスから自動検出されます。
• call — エンコード済みの任意の calldata を送信します：agent call --to <addr> --data 0x... [--value <amt>] [--prefer-native-fee] [--broadcast]。ウォレットは任意のコントラクトを呼び出せます（V3 モデルでは権限のスコープ設定はありません）。
• send-native --direct — ValueForwarder コントラクトを経由せず、EOA へ直接送金します。
• 権限のスコープ設定なし — V3 埋め込みウォレットは、任意のコントラクトを呼び出し、保有する任意の金額を使用できます。コントラクトごとのホワイトリストや支出上限はありません。ウォレット層ではなく、エージェントのロジックで支出を管理してください。
• セッションの有効期限 — ログインから約1週間です。期限が切れたら、wallet login を再実行してください。

ユーザーへの結果の提示

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

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

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

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

---

トラブルシューティング

問題	修正方法
Wallet not found	wallet list を実行し、次に agent wallet login を実行します
セッションの期限切れ（OMS_SESSION_EXPIRED）	agent wallet login を実行します（有効期間は約 1 週間）
Fee option errors	POLYGON_AGENT_DEBUG_FEE=1 を設定し、ウォレットに POL または手数料トークンがあることを確認します。ネイティブのみのウォレットの場合は、call に --prefer-native-fee を追加します
Trails ウィジェットで受取人が間違っている	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)
├── config.json           # transaction mode (auto | dry-run)
├── builder.json          # publishableKey, omsProjectId, polymarket/EOA keys (encrypted)
├── wallets/<name>.json   # OMS wallet pointer: walletAddress, loginMethod
└── oms/<name>/           # OMS SDK session storage + encrypted credential key