polymarket

Polymarket 取引 (CLOB V2)

スクリプト優先。すべてのワークフローは 1 回の bash 呼び出し + 最大 1 回の wallet_sign_typed_data（ウォレット RPC のためスクリプト化できません）で完結します。動作確認済み: Changelog v5.1.0 を参照してください。

---

TL;DR — 3 ステップで取引

# 1. One-time setup (idempotent — safe to re-run)
python3 scripts/setup.py --all 10        # wrap 10 USDC.e -> pUSD + all approvals

# 2. Find a market
python3 scripts/search.py "trump" --limit 3   # returns token_ids

# 3. Place order
python3 scripts/prepare_order.py <token_id> BUY <price> <size>
# → sign /tmp/poly_order.json via wallet_sign_typed_data
python3 scripts/post_order.py <signature>

すべてのスクリプトは skills/polymarket/scripts/ にあり、作業ディレクトリがスキルフォルダーであることを前提としています。

---

アカウントの前提条件（初回のみ、オンチェーン）

CLOB V2 は pUSD（ERC-20 USDC ラッパー）で決済され、生の USDC.e ではありません。最初の注文の前に、EOA は以下を行う必要があります:

1. Polygon 上で USDC.e を保有する（取引したい額以上の任意の量）。
2. CollateralOnramp.wrap() を介して USDC.e → pUSD にラップする。
3. 3 つの V2 取引所スペンダーに対して approve(pUSD, spender, MAX) を実行する。
4. 同じ 3 つのスペンダーに対して setApprovalForAll(CTF, spender, true) を実行する（SELL/償還に必要）。

scripts/setup.py はこれらすべてを実行し、冪等です: オンチェーンの状態を読み取り、すでに完了している処理はスキップします。ガスは Privy/Alchemy ペイマスターがスポンサーするため、ユーザーの負担は 0 MATIC です。

python3 scripts/setup.py                  # dry-run: show current state + next step
python3 scripts/setup.py --all 10         # wrap 10 USDC.e + approve everything
python3 scripts/setup.py --wrap 50        # wrap more later
python3 scripts/setup.py --approve        # re-issue approvals only

---

スクリプト

スクリプト	目的	ツール呼び出し
setup.py	初回のみのラップ + 承認（冪等）	0–8 wallet_transfer
search.py	イベント/マーケットを検索し、token_ids + リアルタイム価格を返す	0
status.py	残高 + ポジション + 未約定注文 + 最近の取引	0
prepare_order.py	オーダーブックを取得 + EIP-712 ペイロードを構築	0
post_order.py	署名済み注文を送信し、約定を検証	0
cancel.py	1 件の注文（--id）またはすべて（--all）をキャンセルする	0
close_positions.py	すべてのポジションに対して SELL 注文を構築する	0
auth.py	ウォレットから CLOB API キーを確認 / 導出する	0–1 sign

検索

python3 scripts/search.py "ceasefire" --limit 3

• 短いキーワード（trump、btc、ceasefire）を使用し、完全なリテラル質問は使わないでください — 長いクエリはしばしば空の結果を返します。
• 出力 JSON には outcomes[i].token_id（YES = インデックス 0、NO = インデックス 1）と現在価格が含まれます。

注文を出す — 完全なフロー

# 1. Prepare: fetches market info + orderbook, writes /tmp/poly_order.json
python3 scripts/prepare_order.py 7892825...50228 BUY 0.65 10

# 2. Sign (Python in agent runtime, ONE tool call)
#    from core.skill_tools import wallet
#    p = json.load(open('/tmp/poly_order.json'))
#    sig = wallet.wallet_sign_typed_data(
#        domain=p['domain'], types=p['types'],
#        primaryType=p['primaryType'], message=p['message']
#    )['signature']

# 3. Post: submits and prints order ID + fill status + tx hash
python3 scripts/post_order.py 0xSIGNATURE

1 件またはすべてのポジションをクローズする

python3 scripts/close_positions.py                # all positions
python3 scripts/close_positions.py --token_id X   # one position
# → writes one /tmp/poly_close_N.json per position; sign each + post

---

YES / NO とオーダーブック

すべてのバイナリマーケットには 2 つの補完的なトークンがあります: YES + NO ≈ $1.00。

ベット	アクション	使用するもの	買値
イベントが発生する	BUY YES	outcomes[0].token_id	YES 価格
イベントが発生しない	BUY NO	outcomes[1].token_id	NO 価格

購入しようとしているトークンのブックを必ず確認してください:

• BUY → エントリー ≈ best_ask
• SELL → イグジット ≈ best_bid
• 0.01 / 0.99 が見える場合、間違ったトークンのブックを見ています。

---

注文ルール (CLOB V2)

• 最小注文額: $1（つまり price × size ≥ 1.0）
• 最小サイズ: 5 株
• ティック: prepare_order.py によって自動的に正規化されます（通常は $0.01）
• signatureType: Privy ウォレットでは常に 0（EOA）

V2 のワイヤーフォーマットは厳格です — post_order.py はすでにこれを処理していますが、ペイロードを手動で構築する場合は:

• salt は int でなければなりません（文字列ではありません）
• taker / nonce / feeRateBps を送信しないでください（V1 のフィールドで、V2 では削除されています）
• metadata と builder は bytes32 のゼロ（0x + 64 個のゼロ）です

---

認証の更新

CLOB 認証情報（POLY_API_KEY / POLY_SECRET / POLY_PASSPHRASE）は、ウォレット署名から一度導出されると永続します。status.py が 401 を返す場合:

python3 scripts/auth.py --check                   # quick sanity check
python3 scripts/auth.py --prepare 0xWALLET        # build signing payload
# → wallet_sign_typed_data(...)
python3 scripts/auth.py --save 0xSIG 0xWALLET TIMESTAMP

不変条件: --save 内の TIMESTAMP と 0xWALLET は、最新の --prepare と一致している必要があります。401 が続く場合は、新しいタイムスタンプで prepare→sign→save のフロー全体を再実行してください。

---

地域 / VPN

CLOB API は米国の IP から地理的にブロックされています。scripts/common.py は sc-vpn.internal:8080 を介して透過的にルーティングし、最速のリージョンをキャッシュします。エージェント側の操作は不要です。POLY_VPN_REGION=ar でオーバーライドするか、POLY_DISABLE_VPN=true で無効化できます。

---

エラー → 修正

エラー	原因	修正
Invalid order payload	V2 ワイヤーフォーマットが誤っている（文字列の salt / 余分な V1 フィールド）	post_order.py を使用してください（正しい形式で送信されます）
invalid amount for a marketable BUY order ($X), min size: $1	注文額 < $1	価格 × 数量を $1 以上に増やしてください
not enough balance / 買付余力が 0	pUSD がまだラップされていない、またはキャッシュ内の signature_type が一致していない	setup.py --all 10 を実行してから status.py
L2_BALANCE_TOO_LOW	EOA に pUSD がない	さらにラップしてください: setup.py --wrap N
order_version_mismatch	古い V1 署名スキーマ	prepare_order.py を再実行してください（V2 ドメイン version=2 を使用）
401 / Invalid API key	CLOB 認証情報が古い	auth.py の更新フロー
403 geo-block	VPN が正常でない	再試行してください。それでも続く場合は、POLY_VPN_REGION を別のリージョンに設定してください
オーダーブックが 0.01 / 0.99 を示す	誤ったアウトカムのオーダーブックを見ている	実際に購入する予定の token_id を使用してください

既知の一時的エラー

• Privy / Alchemy paymaster の HTTP 500 は、オンチェーン呼び出しを短時間に連続して実行する際に発生することがあります。
• これは通常、一時的なインフラの揺らぎであり、恒久的なウォレット/スキルの問題ではありません。
• 実用的な修正: 約 10 秒待ってから同じステップを再試行してください。

---

アーキテクチャの概要

• ウォレット: Privy EOA、signatureType=0。エージェントは wallet_sign_typed_data 経由で EIP-712 に署名します。エージェントのコンテキストに秘密鍵はありません。
• ガス: スポンサー付き（Alchemy paymaster）— すべてのオンチェーン呼び出しは wallet_transfer を経由します。
• 担保: pUSD（0xC011a7E1...DFB）、6 桁の小数、USDC.e を 1:1 でラップ。
• 取引所: CTF Exchange V2（バイナリ）、Neg-Risk Adapter、Neg-Risk Exchange V2 — SELL/決済のために 3 つすべてを承認する必要があります。
• CLOB: https://clob.polymarket.com（V2 バックエンド、2026 年 4 月 28 日から稼働中）。L1 = ウォレット署名、L2 = 派生 API キーによる HMAC。

---

変更履歴

• v6.0.1 — バグ修正: (1) scripts/common.py::save_env_var() が .env の末尾改行欠落をガードし、キーの連結を防止するようになりました。(2) scripts/close_positions.py を V1 ワイヤーフィールドから CLOB V2 スキーマ（timestamp/metadata/builder、ドメイン version=2）に移行し、prepare_order.py と整合させました。短時間に連続して呼び出した際に時折発生する Privy/Alchemy paymaster の HTTP 500 に関する「既知の一時的エラー」の注記を追加しました（約 10 秒後に再試行）。
• v6.0.0 — メジャー: 明確さを期した SKILL の全面的な書き直し（「取引までの 3 ステップ」）、一度きりのラップ + 承認のための新しい冪等な setup.py、CLOB V2 でエンドツーエンドのライブ検証済み（BUY 0x43f20c67...20b653 → SELL 0x19f475e4...fedde1、5 NO @ 0.989 → @ 0.988、約 $0.005 のスリッページ）。V1 時代のフローを完全に置き換えます。
• v5.1.0 — setup.py（冪等なラップ + 承認）を追加。明確さを期した SKILL の全面的な書き直し。ライブ検証済み: BUY 0x43f20c67...20b653、SELL 0x19f475e4...fedde1（5 NO @ 0.989 → @ 0.988、約 $0.005 のスリッページ）。
• v5.0.5 — CLOB V2 ワイヤーフォーマットの修正: salt は int でなければなりません。taker/nonce/feeRateBps を削除。
• v5.0.4 — V2 EIP-712 ドメイン（version=2）、V2 コントラクト、V2 注文フィールドに移行。
• v5.0.0 — スクリプト優先のアーキテクチャ（BUY: 8 回の呼び出し → 3 回）。