polymarket-skill

Polymarket Skill (CLOB V2)

セッションの初期化

polymarket コマンドを実行する前に、Polymarket キーが設定されていることを確認してください:

agent polymarket proxy-wallet

これが ok: true と eoaAddress および proxyWalletAddress を返した場合、キーは設定済みであり、直接取引に進むことができます。エラーになる場合、ユーザーは set-key を実行する必要があります（以下のオンボーディングを参照）。

---

3 つのアドレスの理解

すべての Polymarket ユーザーは 3 つのアドレスを持っています。混同しないでください:

名前	内容	用途
EOA	秘密鍵の所有者。CLI 出力では eoaAddress として表示されます	トランザクションと CLOB 注文に署名します。approve を実行する場合にのみガス用の POL が必要です
プロキシウォレット	CLI 出力では proxyWalletAddress として表示されます。Polymarket の UI で「あなたのアドレス」として表示されるものです	pUSD とアウトカムトークンを保持します。CLOB の maker です
スマートウォレット	OMS ウォレット（agent wallet）です	取引ごとに USDC.e でプロキシウォレットに資金を供給します（自動的に pUSD にラップされます）

取引について: USDC.e は OMS スマートウォレット → プロキシウォレット → 自動的に pUSD にラップ → CLOB 注文、という流れで移動します。プロキシウォレットが取引のアイデンティティです。

---

取引前のチェックリスト

取引を発注する前に、次の 4 点を順番に確認してください:

1. EOA キーが設定されている

agent polymarket proxy-wallet
# → must return ok: true with eoaAddress and proxyWalletAddress

2. Polymarket で利用規約に同意済み ← EOA ごとに 1 回、永続的

• https://polymarket.com にアクセスし、EOA アドレスで接続して利用規約に同意します
• 利用規約に同意していない場合、CLOB の注文投稿は not authorized で失敗します
• この EOA で Polymarket を取引したことがある場合、利用規約には同意済みです — この手順は省略してください

3. V2 取引所に対するプロキシウォレットの承認が設定されている ← V2 移行後はすべてのユーザーに必要

• 承認により、プロキシウォレットが V2 の CTF 取引所コントラクトと CollateralOnramp とやり取りできるようになります
• すべてのユーザーは V2 移行（2026 年 4 月 28 日）後に approve --broadcast を実行する必要があります — 古い取引所コントラクトに対する V1 の承認は引き継がれません
• V2 の承認を一度実行すれば、その EOA に対してオンチェーンで永続的です

4. スマートウォレットに USDC.e がある ← 取引ごとに必要、最低 $1

agent balances
# → check USDC.e balance (0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)
# → must have at least $1 USDC.e to place any order
# → USDC.e is auto-wrapped to pUSD during the buy flow

---

オンボーディング: 初回セットアップ

オプション A — メールログインを使用する場合（既存の Polymarket アカウント）

ステップ 1: Polymarket から秘密鍵を取得する

1. Go to: https://reveal.magic.link/polymarket
2. Connect/authenticate with the same email used for Polymarket
3. Copy the exported private key (0x...)

ステップ 2: キーを CLI にインポートする

agent polymarket set-key <privateKey>

出力で eoaAddress と proxyWalletAddress が確認できます。

ステップ 3: ユーザーにアドレスを表示する

agent polymarket proxy-wallet

ユーザーに伝えてください: 「あなたの EOA は <eoaAddress> です — 1 回限りの承認ステップのために少量の POL が必要です。あなたの Polymarket 取引アドレス（プロキシウォレット）は <proxyWalletAddress> です — ここにあなたの pUSD とアウトカムトークンが保管されます。」

ステップ 4: ガス用の POL で EOA に資金を供給する（承認ステップのみ）

agent send-native --to <eoaAddress> --amount 0.1 --broadcast

EOA は 1 回限りの approve トランザクションにのみ POL を必要とします。それ以降、取引には EOA からのガスは不要です。

ステップ 5: 利用規約に同意する

1. Go to https://polymarket.com
2. Connect with the EOA address
3. Accept Terms of Service when prompted

ステップ 6: V2 用のプロキシウォレット承認を設定する（1 回限り、永続的）

agent polymarket approve --broadcast

これは V2 取引所コントラクトと CollateralOnramp の承認を設定します。オンチェーンで永続的です — この EOA に対して再度実行する必要はありません。

オプション B — builder EOA を使用する場合（Polymarket アカウントなし）

ステップ 1: アドレスを確認する

agent polymarket proxy-wallet

ステップ 2: 利用規約に同意する（必須）

1. Go to https://polymarket.com
2. Connect with the EOA address shown above
3. Accept Terms of Service when prompted

ステップ 3: ガス用の POL で EOA に資金を供給する

agent send-native --to <eoaAddress> --amount 0.1 --broadcast

ステップ 4: V2 用のプロキシウォレット承認を設定する（1 回限り）

agent polymarket approve --broadcast

---

コマンド

マーケットを閲覧する

# List top markets by volume
agent polymarket markets

# Search by keyword
agent polymarket markets --search "bitcoin" --limit 10

# Paginate
agent polymarket markets --limit 20 --offset 20

マーケットごとの主な出力フィールド:

• conditionId — すべての取引コマンドに必要な ID
• question — マーケットが問いかけている内容
• yesPrice / noPrice — 現在の確率（0 から 1、例: 0.65 = 65%）
• negRisk — true の場合、このマーケットを取引する前にネッグリスクの承認を設定してください
• endDate — マーケットが解決する時期

単一のマーケットを取得する

agent polymarket market <conditionId>

注文を発注する前に価格とトークン ID を確認するために使用します。

プロキシウォレットのアドレスを表示する

agent polymarket proxy-wallet

どの EOA とプロキシウォレットが有効であるかを確認します。プロキシウォレットは pUSD とトークンが保管される場所です。

承認の設定 (V2 移行後に必須)

# Standard markets
agent polymarket approve --broadcast

# Neg-risk markets (only if you see negRisk: true on a market you want to trade)
agent polymarket approve --neg-risk --broadcast

すべてのユーザーは V2 移行後にこれを実行する必要があります — 旧取引所コントラクトに対する以前の V1 承認は引き継がれません。V2 の承認が対象とするのは、pUSD → V2 取引所、CTF → V2 取引所、および USDC.e → CollateralOnramp (ラッピング用) です。一度設定すると、オンチェーンで永続します。

ポジションの購入

# Dry-run first — always check before executing
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount>

# Execute — funds proxy wallet, wraps USDC.e → pUSD, then places order
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount> --broadcast

# If proxy wallet already has pUSD from a previous failed order (skip the funding step)
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount> --skip-fund --broadcast

# Limit order — fill only at this price or better
agent polymarket clob-buy <conditionId> YES <usdcAmount> --price 0.45 --broadcast

仕組み:

1. スマートウォレットが usdcAmount の USDC.e をプロキシウォレットに送金します (OMS トランザクション)
2. プロキシウォレットが CollateralOnramp 経由で USDC.e → pUSD にラッピングします (オンチェーン、EOA ガス)
3. CLOB の BUY 注文を発注します: maker=プロキシウォレット、signer=EOA (オフチェーン、ガスなし)
4. 約定時にトークンがプロキシウォレットに到着します

注文タイプ:

• --price なし: FOK 成行注文 (全量約定またはキャンセル)
• --fak: FAK 成行注文 (部分約定を許可)
• --price 0.x: GTC 指値注文 (約定またはキャンセルまでオープンのまま)

最小注文サイズ: $1。 CLOB は $1 未満の注文を拒否します。入金+ラッピングのステップが実行されたのに注文が拒否された場合、pUSD はプロキシウォレットに残ります — 再試行時は --skip-fund を使用してください。

ポジションの売却

# Dry-run first
agent polymarket sell <conditionId> YES|NO <shares>

# Execute
agent polymarket sell <conditionId> YES|NO <shares> --broadcast

# Limit sell
agent polymarket sell <conditionId> YES <shares> --price 0.80 --broadcast

<shares> はアウトカムトークンの数量です (USD ではありません)。シェア数は positions から取得してください。 売却は完全にオフチェーンです — ガスもオンチェーントランザクションもありません。代金はプロキシウォレットに pUSD として受け取られます。

ポジションの確認

agent polymarket positions

プロキシウォレット内のすべてのオープンポジションを、現在価値、損益、アウトカムとともに表示します。

オープン注文の確認

agent polymarket orders

まだオープンな GTC 指値注文を一覧表示します (FOK/FAK 注文は「オープン」になることはありません — 即座に約定またはキャンセルされます)。

注文のキャンセル

agent polymarket cancel <orderId>

orderId は orders コマンド、または clob-buy の出力の orderId フィールドから取得してください。

---

完全自律型取引フロー

# ── FIRST TIME (run once per EOA) ──────────────────────────────────────

# 1. Import Polymarket private key
agent polymarket set-key 0x<yourPrivateKey>
# → save eoaAddress and proxyWalletAddress

# 2. Accept ToS at https://polymarket.com (connect EOA, accept when prompted)

# 3. Fund EOA with POL for the one-time approval tx
agent send-native --to <eoaAddress> --amount 0.1 --broadcast

# 4. Set V2 approvals (one-time, permanent — covers pUSD, CTF, and CollateralOnramp)
agent polymarket approve --broadcast

# ── RETURNING USER ──────────────────────────────────────────────────────
# If V2 approvals were already set: skip steps 1-4, go straight to trading.
# NOTE: V1 approvals (pre-April 28 2026) do NOT carry over — re-run approve once.

# ── FIND A MARKET ────────────────────────────────────────────────────────

# 5. Search for markets
agent polymarket markets --search "bitcoin" --limit 10

# 6. Get details on a specific market
agent polymarket market 0x<conditionId>
# → check: yesPrice, noPrice, negRisk, endDate
# → if negRisk: true → run approve --neg-risk --broadcast first

# ── ENTER A POSITION ────────────────────────────────────────────────────

# 7. Dry-run to confirm
agent polymarket clob-buy 0x<conditionId> YES 5
# → review: currentPrice, proxyWalletAddress, flow (includes pUSD wrapping)

# 8. Execute
agent polymarket clob-buy 0x<conditionId> YES 5 --broadcast
# → check: orderStatus === "matched"

# ── MANAGE ──────────────────────────────────────────────────────────────

# 9. Check positions
agent polymarket positions
# → review: size (shares), curPrice, cashPnl

# 10. Sell when ready
agent polymarket sell 0x<conditionId> YES <shares> --broadcast
# → orderStatus === "matched" means pUSD is back in proxy wallet

---

自律型エージェントの意思決定ロジック

購入するかどうかを判断する場合:

1. proxy-wallet を実行 — EOA とプロキシウォレットのアドレスを確認します
2. balances を実行 — スマートウォレットに少なくとも $1 の USDC.e があることを確認します
3. positions を確認 — すでに保有しているポジションを二重に購入しないようにします
4. markets を確認 — yesPrice/noPrice を確率の入力として使用します
5. 対象マーケットの negRisk を確認 — true の場合、neg-risk の承認が設定されていることを確認します
6. 以前の試行でプロキシウォレットに十分な pUSD がすでにある場合は --skip-fund を使用します
7. 常にまずドライランを実行し、その後ブロードキャストします

売却するかどうかを判断する場合:

1. positions から現在の size (シェア数) を取得します
2. curPrice と avgPrice を比較して損益を評価します
3. 即時イグジットには成行売り (sell --broadcast) を使用します
4. より良い価格を待つには指値売り (--price 0.x --broadcast) を使用します

---

トラブルシューティング

エラー	原因	対処
No EOA key found	set-key が実行されていない	agent polymarket set-key <pk> を実行してください
Could not create api key (stderr のみ)	ToS に同意していない	致命的ではありません — CLI は deriveApiKey で再試行し、成功する場合もあります。注文も失敗する場合は、polymarket.com にアクセスし、EOA で ToS に同意してください
CLOB order error: not authorized	ToS に同意していない	polymarket.com にアクセスし、EOA ウォレットを接続して利用規約に同意してください
insufficient funds for gas	EOA に POL がない	agent send-native --to <eoaAddress> --amount 0.1 --broadcast
Market not found	低出来高またはクローズ済みのマーケット	マーケットが解決済みの可能性があります。別の検索語で --search を試してください
Market has no tokenIds	クローズ済みのマーケット	endDate を確認してください — マーケットは解決済みです
FOK での orderStatus: "unmatched"	成行価格に流動性がない	部分約定には --fak を、指値注文には --price 0.x を試してください
invalid amount for a marketable BUY order ($X), min size: $1	CLOB の最小額を下回っている	少なくとも $1 を使用してください。pUSD がすでに入金済みの場合は、--skip-fund で再試行してください
Wallet not found: main	ログインしていない	agent wallet login を実行してください
セッションの期限切れ (OMS_SESSION_EXPIRED)	ログインセッションの失効 (約 1 週間)	agent wallet login を実行してください
V2 移行後に承認トランザクションがリバートする	V1 の承認 — 誤った取引所コントラクト	V2 コントラクトに対して agent polymarket approve --broadcast を再実行してください

---

エージェント向けの重要事項

• CLOB V2 が有効です（2026 年 4 月 28 日以降）。担保は pUSD であり、USDC.e ではありません。
• すべてのコマンドはデフォルトでドライランです。 approve、clob-buy、sell は --broadcast を付けない限り何も行いません。
• すべてのユーザーに V2 の承認が必要です。 旧取引所コントラクトでの V1 承認は引き継がれません。移行後に一度 approve --broadcast を実行してください。
• clob-buy はフロー全体を自動的に処理します: スマートウォレットから USDC.e をプロキシウォレットへ転送 → USDC.e を pUSD にラップ → その後 CLOB 注文を発注します（--skip-fund を指定しない場合）。
• ポジションはプロキシウォレットに存在し、OMS スマートウォレットにはありません。positions はプロキシウォレットを照会します。
• 売却は無料です。 ガスもオンチェーン tx も不要です。CLOB 経由の売却は署名されたオフチェーンメッセージのみです。収益は pUSD です。
• orderStatus: "matched" は取引が約定したことを意味します。"unmatched" は FOK が失敗した（流動性がない）ことを意味します。
• 手数料はマッチ時にプロトコルによって決定されます。 メイカーが手数料を支払うことはありません — 支払うのはテイカーのみです。注文に feeRateBps はありません。
• プロキシウォレットのアドレスは決して変わりません。 EOA から CREATE2 によって決定論的に導出されます。
• stderr の Could not create api key は致命的ではありません。 CLI がこれを自動的に処理します。