evm_swap
Execute a spot swap on an EVM chain (non-custodial, two-phase, OPT-IN).
chain must be named explicitly -- nothing routes to an EVM chain by default and a Solana route never fails over onto one. Base only today.
Without signed_transaction: returns an UNSIGNED EIP-1559 transaction under 'evm_transaction' (Crank fills nonce, gas and 1559 fees, and re-estimates gas against current state). Sign it with YOUR wallet for taker -- Crank never signs and never holds a key. The first time a given ERC-20 is sold the response is phase='approval_required' with an 'approval_transaction' for the EXACT sell amount (never an unlimited allowance); sign that, wait for its receipt, then call again.
With signed_transaction: broadcasts the signed RLP and returns tx_hash plus a 'verification' block -- receipt status (a MINED transaction is NOT necessarily a SUCCESSFUL one), the fill parsed from the ERC-20 Transfer log, and a balance cross-check. Gate follow-on decisions on verification.status == 'success'.
Value-bearing: the SAME technology service fee schedule as every other Crank venue, at the same rate -- there is no per-chain fee differentiation. Paper trading mode returns a real 0x quote and builds nothing signable.
idempotency_key (optional): reuse the SAME key across the SWAP build call and its signed_transaction completion retry. Do NOT carry a key across the approval_required response into the swap build that follows it -- those are two different calls, and the approval leg is not deduplicated at all (it builds nothing that could be duplicated: an ERC-20 approve SETS an allowance rather than adding to one, so re-issuing it is a no-op).
replace_nonce / replace_max_fee_per_gas / replace_max_priority_fee_per_gas (optional, all three together, BUILD leg only): rebuild this swap at the nonce of a transaction you already broadcast that is stuck unmined, with both EIP-1559 fee fields bumped past the ones it carries so a node accepts it as a replacement instead of rejecting it as underpriced. Pass the stuck transaction's own nonce and fee pair (decimal or 0x-hex). Sign and broadcast the result as normal -- whichever of the two transactions lands, only one can, because they share a nonce.
A replacement build IS billed the technology service fee, as its own action. It is a fresh 0x quote, a fresh gas estimate and a fresh transaction built against current state, and the fee is not suppressible on a leg the caller triggers by passing three parameters -- that would be a free-swap switch. Budget for it before replacing: a stuck swap that you replace costs two fees, not one.
Use a FRESH idempotency_key for a replacement call (or omit it). The replace_* values are part of the idempotency identity, so carrying the stuck build's key forward raises IDEMPOTENCY_CONFLICT (non-retryable) -- same key, different arguments. That refusal is deliberate: the alternative would be replaying the cached original build back at you, old nonce and old fees, which is silently NOT the replacement you asked for. Retries of the SAME replacement, under its own fresh key, deduplicate normally.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | base | |
| taker | Yes | ||
| verify | No | ||
| buy_token | Yes | ||
| caller_id | No | ||
| sell_token | Yes | ||
| sell_amount | Yes | ||
| pay_in_crank | No | ||
| slippage_bps | No | ||
| replace_nonce | No | ||
| payment_header | No | ||
| idempotency_key | No | ||
| pre_buy_balance | No | ||
| signed_transaction | No | ||
| expected_buy_amount | No | ||
| replace_max_fee_per_gas | No | ||
| replace_max_priority_fee_per_gas | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||