swap
Initiate a token swap (same-chain or cross-chain) from one of the user's picnic smart accounts, routed through Picnic's swap aggregator. Returns a sign_url and a resource_uri for live status updates. Execution starts as soon as the user signs.
Routing fans out across CowSwap, 0x, Bungee, Squid, Li.Fi, and deBridge. By default the aggregator picks the best quote; pass provider to force a specific source.
Source constraint: swaps are only supported from picnic-type smart accounts. The gnosisPay card safe is not a valid source — to convert funds sitting on the card account, first transfer them to the Picnic account, then swap.
Required scopes: propose:swap, execute:swap
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
source_smart_account_address | string | yes | Source picnic smart account holding the from asset. Must be one of the passkey's controlled picnic accounts on source_chain_id; gnosisPay sources are rejected. Use get_smart_accounts to discover available addresses. |
source_chain_id | number | yes | Chain ID of the source smart account. Must equal the chainId encoded in from_asset_id — mismatch is rejected upfront. |
from_asset_id | string | yes | Source asset id — eip155:{chainId}/erc20:{address} for ERC-20s, eip155:{chainId}/bep20:{address} on BSC, or eip155:{chainId}/slip44:60 for the chain's native coin. |
to_asset_id | string | yes | Destination asset id, same format. May be on a different chain (cross-chain swap). |
formatted_amount | string | yes | Decimal amount of the source asset in its display units, e.g. "1.5" for 1.5 USDC. Server resolves decimals from from_asset_id. |
slippage | number | no | Slippage as a fraction (default 0.01 = 1%, max 0.5). |
provider | string | no | Force a specific provider — one of cowswap, 0x, lifi, bungee, squid, debridge. Default: best of all. |
Returns:
| Field | Type | Description |
|---|---|---|
action_id | string | UUID for the pending action. |
status | string | Always "proposed" immediately after this tool returns. |
summary | string | Human-readable summary the user sees on the sign page. |
sign_url | string | URL the user opens to authorize with their passkey. |
resource_uri | string | picnic://action/{action_id}. Subscribe for notifications/resources/updated. |
simulation_url | string | Tenderly preview URL. |
expires_at | date | ISO timestamp; 10 minutes after creation. |
Slippage warnings: the sign page surfaces a yellow banner when slippage is ≥1% and a red banner when it exceeds 5%. Anything above 5% usually means a thin pool, an unusual route, or a scam token.
Action lifecycle (status enum):
proposed → signed → submitted → broadcast → executed (success path)
Other terminal states: failed, expired, rejected.
Example prompts:
"Swap 100 USDC for ETH on Base."
"Bridge 50 USDC from Base to USDC on Polygon."