crypto-agent-trading

スキル：crypto-agent-trading

エージェントの機能要件

このスキルを使用するには、エージェントのプラットフォームが以下の機能をサポートしている必要があります。必須の機能がプラットフォームにない場合、このスキルは機能しません。

機能	必須	詳細
シェルコマンドの実行	はい	npx tsx ./scripts/... を実行し、標準出力を取得できる必要があります
環境変数	はい	シェル環境から CDC_API_KEY と CDC_API_SECRET を読み取れる必要があります
JSON の解析	はい	スクリプトの標準出力から構造化された JSON を解析し、フィールドを抽出できる必要があります
複数ターンの会話	はい	取引では、複数のユーザーターンにまたがる見積もり → 確認のフローを使用します
永続メモリ	いいえ	confirmation_required の設定に使用します。サポートされていない場合、取引は常に確認を求めるようにしてください
経過時間の認識	いいえ	見積もりの有効期限（countdown フィールド）の確認に使用します。サポートされていない場合は常に確認を試み、invalid_quotation エラーを適切に処理してください

重要：このスキルの仕組み

すべての API 操作には、必ず TypeScript スクリプトを使用してください。curl、fetch、その他の HTTP メソッドで API を直接呼び出してはいけません。

スクリプトはリクエストの署名、エラー処理、レスポンスのフォーマットを行います。スクリプトを使用しない場合：

• HMAC 署名がないため、リクエストは失敗します
• レスポンスがフィルタリングも構造化もされません

ユーザーからのリクエストごとに、以下から該当するコマンドを見つけて npx tsx で実行してください。JSON の出力を読み取り、それに基づいて対応してください。

設定

• BASE_URL：https://wapi.crypto.com
• CDC_API_KEY：{{env.CDC_API_KEY}}
• CDC_API_SECRET：{{env.CDC_API_SECRET}}
• CONFIRMATION_REQUIRED：{{memory.confirmation_required}}（デフォルト：true）
• SKILL_DIR：この SKILL.md ファイルが置かれているディレクトリです。このファイルを読み込んだパスから特定してください（例：/home/user/skills/crypto-agent-trading/SKILL.md を読んだ場合、SKILL_DIR は /home/user/skills/crypto-agent-trading です）。

環境の設定

• 使用前に、CDC_API_KEY と CDC_API_SECRET の両方を環境変数として設定する必要があります。

• スクリプトを実行する前に、次のコマンドを実行して両方の変数が設定されているか確認してください：

  echo "CDC_API_KEY=${CDC_API_KEY:+set}" "CDC_API_SECRET=${CDC_API_SECRET:+set}"
  

  どちらかの出力が set ではなく空の場合、ユーザーに次のように案内してください：

  「API 認証情報が設定されていません。処理を続行する前に、ターミナルで設定してください：

  export CDC_API_KEY="your-api-key"
  export CDC_API_SECRET="your-api-secret"
  

  API キーは https://help.crypto.com/en/articles/13843786-api-key-management で生成できます。 設定が完了したらお知らせください。」

  その後、ユーザーから確認があるまで停止して待機してから再試行してください。

• スクリプトが MISSING_ENV エラーを返した場合も同様に扱い、変数を設定するようユーザーに案内して待機してください。

スクリプトコマンド

すべての API 操作は、必ずこれらのスクリプトを通じて行ってください。 スクリプトが署名、実行、フィルタリング、エラーのフォーマットを処理します。シェルから適切なコマンドを実行し、JSON の出力を解析してください。

前提条件： npx tsx（Node.js 18 以降が必要です。tsx は npx によって自動的に取得されます）。

重要： 以下のスクリプトパスでは、このスキルのルートディレクトリを表すプレースホルダーとして $SKILL_DIR を使用しています。この SKILL.md ファイルを読み込んだパスから特定するか、スキルディレクトリに cd してパスに ./scripts/... を使用してください。どちらの方法でも構いません。

アカウントコマンド

# Filtered non-zero balances (scope: fiat | crypto | all)
npx tsx $SKILL_DIR/scripts/account.ts balances [fiat|crypto|all]

# Single token balance lookup
npx tsx $SKILL_DIR/scripts/account.ts balance <SYMBOL>

# Weekly trading limit
npx tsx $SKILL_DIR/scripts/account.ts trading-limit

# Find funded source wallets for a trade type
npx tsx $SKILL_DIR/scripts/account.ts resolve-source <purchase|sale|exchange>

# Kill switch — revoke API key
npx tsx $SKILL_DIR/scripts/account.ts revoke-key

取引コマンド

取引は2段階のフローで行います。まず見積もりを取得し、次に注文を確定します。

# Step 1 — Get quotation (type: purchase | sale | exchange)
npx tsx $SKILL_DIR/scripts/trade.ts quote <type> '<json-params>'
# Returns: {"ok": true, "data": {"id": "<quotation-id>", "from_amount": {...}, "to_amount": {...}, "countdown": 15, ...}}

# Step 2 — Confirm order: pass the data.id from Step 1 as <quotation-id>
npx tsx $SKILL_DIR/scripts/trade.ts confirm <type> <quotation-id>

# View recent transactions
npx tsx $SKILL_DIR/scripts/trade.ts history

ユーザーの意図を取引タイプに対応付ける方法：

ユーザーの発言	取引タイプ	From	To
「100 USDでCROを購入」	purchase	USD（法定通貨）	CRO（暗号資産）
「0.1 BTCを売却」	sale	BTC（暗号資産）	USD（法定通貨）
「0.1 BTCをETHに交換」	exchange	BTC（暗号資産）	ETH（暗号資産）

取引タイプ別の見積もり用JSONパラメーター：

タイプ	JSONフィールド
purchase	{"from_currency":"USD","to_currency":"CRO","from_amount":"100"} または、代わりに to_amount を使用
sale	{"from_currency":"BTC","to_currency":"USD","from_amount":"0.1","fixed_side":"from"}
exchange	{"from_currency":"BTC","to_currency":"ETH","from_amount":"0.1","side":"buy"}

例 —「100 USDでCROを購入」：

1. 実行します：npx tsx $SKILL_DIR/scripts/trade.ts quote purchase '{"from_currency":"USD","to_currency":"CRO","from_amount":"100"}'
2. 応答から data.id、data.from_amount、data.to_amount、data.countdown を読み取ります。
3. 確認が必要な場合（デフォルト）：ユーザーに「確認してください：100 USDでX CROを購入しますか？有効期限は{countdown}秒です。続行するには「YES」と返信してください。」と尋ねます。
   • ユーザーがカウントダウン以内にYESと答えた場合：npx tsx $SKILL_DIR/scripts/trade.ts confirm purchase <data.id>
4. 確認がオプトアウトされている場合（memory.confirmation_required が false）：確認を求めず、ただちに npx tsx $SKILL_DIR/scripts/trade.ts confirm purchase <data.id> を実行します。

オプトイン／オプトアウト： ユーザーは「確認を求めるのをやめて」と言うと取引を自動実行でき、「確認を必須にして」と言うと確認プロンプトを再度有効にできます。以下のセクション3を参照してください。

コイン検索コマンド

# Search coins
npx tsx $SKILL_DIR/scripts/coins.ts search '{"keyword":"BTC","sort_by":"rank","sort_direction":"asc","native_currency":"USD","page_size":10}'

必須のJSONパラメーター：

パラメーター	タイプ	許可される値
sort_by	文字列	rank、market_cap、alphabetical、volume、performance
sort_direction	文字列	asc、desc
native_currency	文字列	大文字の通貨コード（例：USD）
keyword	文字列	検索文字列。1～100文字。コイン名とシンボルのみを対象に検索
page_size	整数	1ページあたりの結果数

任意： page_token — 次のページを取得するための不透明なトークン（以下のページネーションを参照）。

ページネーション： 応答には has_more（ブール値）と next_page_token（文字列）を含む pagination オブジェクトがあります。has_more が true の場合、次のページを取得するリクエストで next_page_token を page_token として渡します。

各コインの主な応答フィールド： rails_id（取引APIおよびアカウントAPIの currency_id ／ currency と同一です。相互参照に使用します）、price_native、price_usd、percent_change_*_native（過去の期間における価格パフォーマンス。例：percent_change_24h_native）。

出力形式

すべてのスクリプトは、構造化されたJSONを標準出力に出力します。

成功：

{"ok": true, "data": { ... }}

エラー：

{"ok": false, "error": "ERROR_CODE", "error_message": "Human-readable message"}

制約事項

• 検証： スクリプト出力の ok: true が成功の条件です。
• 確認時間枠： 見積もりの有効期間は、見積もりデータの countdown フィールドで定義されます。
• 実行時の警告： 注文の確定に5秒を超える場合は、「注文は送信されましたが、想定より時間がかかっています。「最近の取引を表示」で注文状況を確認してください」と通知します。
• レート制限：
  • 取引は1分あたり最大10件です。
  • API呼び出しは1分あたり最大100回です。
  • HTTP 429（RATE_LIMITED エラー）の場合：同じリクエストを再試行する前に60秒待機します。ユーザーに「レート制限に達しました。再試行する前に60秒お待ちください」と伝えます。

エラー処理

すべてのスクリプトは構造化されたエラーを返します。適切な対応を判断するには、error フィールドを解析します。

スクリプトのエラーコード

スクリプトの JSON 出力に含まれる error の値です。発生した失敗の種類を示します。

エラーコード	意味	エージェントの対応
MISSING_ENV	CDC_API_KEY または CDC_API_SECRET が設定されていません	ターミナルから環境変数を設定するようユーザーに伝えます
API_ERROR	API が 200 以外を返した、または ok !== true でした	「トランザクションに失敗しました：{error_message}」と報告します
INVALID_ARGS	コマンドライン引数が正しくありません	error_message に記載された正しい使い方を示します
QUOTATION_FAILED	API が見積もりリクエストを拒否しました	error_message をユーザーに報告します（以下の API エラーを参照）
EXECUTION_FAILED	注文の確定に失敗しました	報告し、「『Show recent trades』で注文状況を確認してください」と提案します
API_KEY_NOT_FOUND	キーはすでに失効しているか、存在しません	「API キーが見つかりません。すでに失効している可能性があります。」
RATE_LIMITED	リクエストが多すぎます（HTTP 429）	「レート制限に達しました。再試行する前に 60 秒お待ちください。」
UNKNOWN	予期しないエラーです	生の error_message を報告します

ルール： 出力の ok が false の場合は、現在の操作を中止し、上記のガイダンスに従ってエラーをユーザーに報告してください。失敗後に次のステップへ進んではいけません。

よくある API エラー（クイックリファレンス）

以下は、QUOTATION_FAILED、EXECUTION_FAILED、または API_ERROR のレスポンスの error_message 内に含まれる具体的な API エラーコードです。API がリクエストを拒否した理由を示します。

error	意味	対処
not_enough_balance	残高不足です	残高を確認し、取引額を減らします
invalid_currency	通貨コードが認識されません	コイン検索で確認します
invalid_quotation	見積もりの期限が切れているか、すでに使用されています	新しい見積もりをリクエストします
failed_to_create_quotation	見積もりエンジンのエラーです	少し待ってから再試行します
not_eligible_for_prime	Prime の特典を利用できる対象ではありません	Prime を利用せずに進めます
unauthorized	アカウントで取引が承認されていません	サポートに問い合わせます
restricted_feature	アカウントで機能が制限されています	error_message をユーザーに報告します
existing_currency_order_error	既存の注文が処理中です	既存の注文が完了するまで待つか、キャンセルします
viban_purchase_not_enabled	法定通貨から暗号資産への交換が有効になっていません	アカウントでこの機能を利用できません
crypto_viban_not_enabled	暗号資産から法定通貨への交換が有効になっていません	アカウントでこの機能を利用できません
bank_transfer_not_enabled	銀行振込が有効になっていません	アカウントでこの機能を利用できません
missing_parameter	必須パラメーターがありません	スクリプトのバグです。報告してください
failed_to_create_transaction	トランザクションの作成に失敗しました	再試行するか、サポートに問い合わせます
key_not_active	API キーが失効しているか、期限切れです	新しい API キーを生成し、環境変数を更新します
api_key_not_found	キーが存在しないか、別のユーザーに属しています	CDC_API_KEY に正しいキーが設定されているか確認します

動的なエラー（上限超過、通貨の無効化、クールオフなど）の場合は、error と error_message をそのままユーザーに報告してください。詳細については、references/errors.md を参照してください。

---

ロジックとルール

1. 資産とソースの判別

まず取引の種類を特定します。

• 購入 — 法定通貨 → 暗号資産
• 売却 — 暗号資産 → 法定通貨
• 交換 — 暗号資産 → 暗号資産

次にソースウォレットを解決します。

• 購入の場合：npx tsx $SKILL_DIR/scripts/account.ts resolve-source purchase を実行します。このスクリプトは、資金のある法定通貨のエントリーのみを返します。
• 売却または交換の場合：npx tsx $SKILL_DIR/scripts/account.ts resolve-source sale（または exchange）を実行します。このスクリプトは、資金のある暗号資産のエントリーのみを返します。

結果（data.status に基づく）：

• SELECTED → data.currency を自動選択します。
• AMBIGUOUS → data.options から選択するようユーザーに尋ねます。
• EMPTY → ユーザーに「資金のあるウォレットが見つかりません」と伝え、処理を終了します。

「すべて売却」シナリオ： ユーザーが「[TOKEN] をすべて売却」と言った場合、npx tsx $SKILL_DIR/scripts/account.ts balance [TOKEN] を実行します。data.available の数量（または data.balance）を見積もりの from_amount として使用します。

2. 取引の手順（見積もり → 確認 → 実行）

ユーザーが暗号資産の購入、売却、交換を依頼した場合は、必ず次の3段階の手順に従います。

• ステップ A — 見積もりを取得： ユーザーの依頼から JSON パラメーターを作成し（Trade Commands の「Quotation JSON params」表を参照）、次を実行します。 npx tsx $SKILL_DIR/scripts/trade.ts quote <type> '<json-params>' 応答から data.id、data.from_amount、data.to_amount、data.countdown を読み取ります。

• ステップ B — ユーザーに確認：

  • IF memory.confirmation_required が true（または未設定）の場合：
    • 確認文：「確認してください：{from_amount} を {to_amount} と交換しますか？有効期限は {countdown} 秒です。続行するには 'YES' と返信してください。」
    • 有効期限のロジック： ユーザーが countdown 秒経過後に「YES」と返信した場合は、次のように拒否します：「取引を拒否しました：見積もりレートの有効期限が切れています。新しい見積もりを依頼してください。」
    • 有効期間内にユーザーが「YES」と返信した場合に限り、ステップ C を実行します。
  • ELSE（オプトアウト済み）：
    • 通知：「見積もりを受け取りました。自動的に実行に進みます……」
    • 直ちにステップ C に進みます。

• ステップ C — 注文を実行： ステップ A の id を使用して、次を実行します。npx tsx $SKILL_DIR/scripts/trade.ts confirm <type> <data.id>

3. メモリー管理（オプトイン／オプトアウト）

• オプトアウトするには： ユーザーが「確認を求めるのをやめて」または「自動取引を有効にして」と言った場合、memory.confirmation_required を false に更新します。
• オプトインするには： ユーザーが「確認を必須にして」または「手動取引を有効にして」と言った場合、memory.confirmation_required を true に更新します。
• 永続メモリーに対応していないプラットフォーム： お使いのプラットフォームが {{memory.*}} に対応していない場合、最も安全な既定値として confirmation_required は常に true として扱います。

4. エラー処理

• すべてのスクリプト出力には ok フィールドが含まれます。成功と見なすのは ok: true の場合のみです。
• ok が false の場合は、error を読み取り、上記のエラー処理表に従って応答します。
• コマンドが失敗した場合は、次のステップに進まないでください。

5. アカウントと履歴

• 履歴： npx tsx $SKILL_DIR/scripts/trade.ts history を実行し、data のエントリーを表示します。
• 週間取引上限： npx tsx $SKILL_DIR/scripts/account.ts trading-limit を実行し、次の形式で表示します：「📊 週間取引上限：{data.used} / {data.limit} USD（残り：{data.remaining} USD）」。
• 残高（カテゴリー別）：
  • 「法定通貨を一覧表示」の場合：npx tsx $SKILL_DIR/scripts/account.ts balances fiat を実行します。
  • 「暗号資産を一覧表示」の場合：npx tsx $SKILL_DIR/scripts/account.ts balances crypto を実行します。
  • 「すべてを一覧表示」の場合：npx tsx $SKILL_DIR/scripts/account.ts balances all を実行します。重要： まず法定通貨カテゴリーを表示し、その下に暗号資産の残高を表示します。
  • スクリプトは残高がゼロのエントリーを自動的に除外します。出力にカテゴリーのエントリーがない場合は、その見出しの下に「保有資産なし」と表示します。

6. キルスイッチ

• トリガー： ユーザーが「STOP ALL TRADING」、「kill switch」または同様の緊急停止コマンドを入力します。
• memory.confirmation_required の設定にかかわらず、必ず明示的な確認を要求します：
  • 確認メッセージ：「⚠️ 警告：API キーが直ちに失効し、すべての取引が無効になります。取引を再開するには、新しい API キーを生成する必要があります。続行するには「CONFIRM KILL SWITCH」と入力してください。」
  • ユーザーが完全一致するフレーズで返信した場合にのみ実行します。
• 実行： npx tsx $SKILL_DIR/scripts/account.ts revoke-key を実行します。
• 成功時（ok: true）： 「🛑 キルスイッチが作動しました。API キーは失効しました。すべての取引が無効になっています。取引を再開するには、新しい API キーを生成し、環境変数を更新してください。」と通知します。
• API_KEY_NOT_FOUND エラー時： 「API キーが見つかりません。すでに失効しているか、存在しない可能性があります。」と通知します。
• 冪等性： すでに失効しているキーの失効処理はエラーではありません。失効処理が成功した場合と同様に扱います。

7. 残高の表示形式

• 法定通貨の見出し： 「🏦 法定通貨の残高」
• 暗号資産の見出し： 「🪙 暗号資産の残高」
• 法定通貨と暗号資産の両方が要求された場合は、必ず法定通貨のセクションを先に表示します。
• 残高がゼロの資産は表示しないでください。 残高が 0 を超える資産のみを表示します。カテゴリ内のすべての資産の残高がゼロの場合は、その見出しの下に「保有資産なし」と表示します。