swap コマンド
swapコマンドは、Uniswap V3 を経由してトークンをスワップするコマンドです。トークンシンボル（例: USDC, WETH）またはコントラクトアドレス（0x...）を指定して、任意の ERC-20 ペアを交換できます。
重要: dry-run デフォルト
セキュリティ上の理由から、swapコマンドはデフォルトで dry-run（シミュレーション）モードです。 実際にトランザクションを送信するには、--broadcastフラグを明示的に指定する必要があります。
構文
kova swap --name <wallet> --from <token> --to <token> --amount <amount> [options]オプション
| オプション | 必須/任意 | 説明 | デフォルト |
|---|---|---|---|
--name <name> | 必須 | ウォレット名または ID | - |
--from <token> | 必須 | 売却トークン。シンボル（例: USDC）または 0x... アドレス | - |
--to <token> | 必須 | 購入トークン。シンボル（例: WETH）または 0x... アドレス | - |
--amount <amount> | 必須 | 売却量（整数または小数、例: 100, 0.5） | - |
--slippage <pct> | 任意 | スリッページ許容値（%）。範囲: 0.1〜50.0 | 0.5 |
--chain <chain> | 任意 | チェーン名。base / ethereum / polygon / arbitrum / optimism | base |
--broadcast | 任意 | 実際にトランザクションを送信 | false（dry-run） |
--owner | 任意 | passphrase 署名を強制する（OWS API key を使わずローカル passphrase で署名） | false |
--unlimited-approve | 任意 | Permit2 に最大量 + 1 年の expiration で approve（初回 approve トランザクションを省略できるが blast radius が拡大） | false |
--recipient <address> | 任意 | スワップ出力の受け取り先アドレス。--owner 指定時のみ有効 | sender wallet |
--from / --to について
--from と --to にはいずれも次の 2 通りの指定方法があります：
- トークンシンボル — 例:
USDC,WETH,ETH。kova 組み込みの静的レジストリおよびユーザー登録トークン（kova token addで追加）から解決されます。 - コントラクトアドレス —
0x...形式の ERC-20 コントラクトアドレス。オンチェーンのdecimals()/symbol()を取得します。レジストリ未登録の場合は未検証（unverified-address）扱いとなり、警告が表示されます。
--from と --to に同一のトークン（表記が違っても解決後のアドレスが同じ場合も含む）を指定するとエラーになります。
--recipient と --owner の関係
--recipient は --owner フラグとセットでのみ使用できます。agent モード（--owner なし）では、スワップ出力は必ず送信元ウォレットに送られます。compromised agent がスワップ出力を任意アドレスに横流しするリスクを防ぐための制約です。
dry-run vs --broadcast
| モード | 動作 |
|---|---|
| dry-run（デフォルト） | スワップ見積もりのみ実行。トランザクションは送信されません |
--broadcast | Uniswap V3 経由で実際にスワップを実行します |
使用例
シンボル指定 — USDC → WETH（dry-run）
kova swap --name main --from USDC --to WETH --amount 100 --chain base出力例:
{
"ok": true,
"data": {
"dryRun": true,
"swap": {
"from": {
"token": "USDC",
"amount": "100",
"info": {
"kind": "symbol",
"symbol": "USDC",
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"source": "static"
}
},
"to": {
"token": "WETH",
"estimatedAmount": "0.03842",
"minimumAmount": "0.03823",
"info": {
"kind": "symbol",
"symbol": "WETH",
"address": "0x4200000000000000000000000000000000000006",
"decimals": 18,
"source": "static"
}
},
"recipient": "0xB8EC761bf83B4374877e903d217222F2cd5512De",
"route": ["USDC", "WETH"],
"dex": "Uniswap V3 (via Universal Router)",
"gasEstimate": "150000",
"slippage": "0.5%"
},
"permit2": {
"address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
"needsApprove": false,
"needsPermitSign": false
}
}
}シンボル指定 — USDC → WETH（broadcast）
kova swap --name main --from USDC --to WETH --amount 100 --chain base --broadcast出力例:
{
"ok": true,
"data": {
"dryRun": false,
"txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"explorerUrl": "https://basescan.org/tx/0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
"swap": {
"from": {
"token": "USDC",
"amount": "100",
"info": {
"kind": "symbol",
"symbol": "USDC",
"address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"decimals": 6,
"source": "static"
}
},
"to": {
"token": "WETH",
"estimatedAmount": "0.03842",
"minimumAmount": "0.03823",
"info": {
"kind": "symbol",
"symbol": "WETH",
"address": "0x4200000000000000000000000000000000000006",
"decimals": 18,
"source": "static"
}
},
"recipient": "0xB8EC761bf83B4374877e903d217222F2cd5512De",
"route": ["USDC", "WETH"],
"dex": "Uniswap V3 (via Universal Router)"
},
"gasSponsored": false
}
}コントラクトアドレス指定
レジストリ未登録のトークンを対象にする場合はアドレスを直接指定します。
kova swap \
--name main \
--from 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
--to WETH \
--amount 50 \
--chain base \
--broadcast注意: レジストリ未登録の
0x...アドレスを使用すると、未検証トークンの警告が出力されます。コントラクトアドレスが正しいことを必ず確認してください。
スリッページを調整する
ボラティリティが高い場面では --slippage を引き上げます。
kova swap --name main --from USDC --to WETH --amount 100 --chain base --slippage 1.0 --broadcast出力を別アドレスへ（owner モード）
kova swap \
--name main \
--from USDC \
--to WETH \
--amount 100 \
--chain base \
--owner \
--recipient 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
--broadcastスワップフロー（推奨）
実際のスワップは以下の 2 ステップで行うことを推奨します。
ステップ 1: dry-run で内容を確認
kova swap --name main --from USDC --to WETH --amount 100 --chain base確認事項:
fromのシンボルと量が正しいかtoの推定受取量が妥当か- チェーンが正しいか
- スリッページ設定が適切か
ステップ 2: --broadcast で実行
kova swap --name main --from USDC --to WETH --amount 100 --chain base --broadcastよくあるエラーと対処法
WALLET_NOT_FOUND
{
"ok": false,
"error": {
"code": "WALLET_NOT_FOUND",
"message": "Wallet 'main' not found."
}
}対処法: kova wallet info でウォレット名を確認する。
INVALID_PARAMS（同一トークン）
{
"ok": false,
"error": {
"code": "INVALID_PARAMS",
"message": "from と to は異なるトークンを指定してください..."
}
}対処法: --from と --to に異なるトークンを指定する。シンボルとアドレスが異なっていても、解決後のアドレスが同じ場合も拒否されます。
INVALID_PARAMS（スリッページ範囲外）
{
"ok": false,
"error": {
"code": "INVALID_PARAMS",
"message": "slippage は 0.1〜50.0 (%) の範囲で指定してください..."
}
}対処法: --slippage に 0.1〜50.0 の値を指定する。
INVALID_PARAMS（--recipient は --owner 必須）
{
"ok": false,
"error": {
"code": "INVALID_PARAMS",
"message": "--recipient は --owner 指定時のみ利用できます。..."
}
}対処法: --recipient を使う場合は必ず --owner も付ける。
INSUFFICIENT_BALANCE
{
"ok": false,
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "Insufficient balance. Required: 100 USDC, Available: 50 USDC"
}
}対処法: kova balance で残高を確認し、必要量を入金する。
POLICY_DENIED
ポリシー（spending_limit 等）でスワップが拒否された場合に発生します。kova policy list で内容を確認し、必要なら kova policy update で調整してください。
CHAIN_NOT_SUPPORTED
{
"ok": false,
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"message": "Chain 'unknown-chain' is not supported."
}
}対処法: --chain に指定できる値は base（デフォルト）/ ethereum / polygon / arbitrum / optimism です。
ポリシー制御
swap は policy-gated 操作です。spending_limit ポリシーが設定されている場合、スワップに使う --from トークンの量がポリシーで評価されます。agent モードでは OWS server 側のポリシーで gate されます。詳細は policy コマンド を参照してください。
broadcast 後のトークン自動登録
--broadcast が成功すると、スワップで受け取ったトークン（--to）が kova balance のサマリーに表示されるよう自動的にユーザートークンレジストリへ登録されます。ただし、次の場合は登録をスキップします：
- ネイティブトークン（ETH 等）— 常に balance に表示されるため不要
- 組み込み済みの主要トークン（USDC / USDT / JPYC 等）
- 既知トークンと同シンボル・別アドレスの場合（symbol-spoofing 防止）
スキップされた場合は kova token add で手動登録できます。