Developer guide

EVM

7 min read

Supported networks

Direct EVM transfers work across every enabled EVM network through one relayer and authorization model. See the Roadmap for which networks and execution modes are currently available.

Transfer lifecycle

Create a quote through the official SDK, accept it with an idempotency key, then follow the asynchronous operation and its events. The platform validates the tenant context, policy and quote before it creates a signature request or submits a transaction. A submitted transaction is never assumed successful: receipts and ERC-20 Transfer logs are used during reconciliation.

Assets and the operations they take

The network and the contract address identify an asset; the symbol only names it. GET /v1/assets publishes contractAddress on every token row, and a network can list two rows with the same symbol: on Arbitrum Sepolia and Base Sepolia, one USDC with canonicality: "canonical", the token its issuer published on that network, and one with canonicality: "non-canonical-test", the token this deployment issued. Check chainId and contractAddress, never the symbol, before sending funds to or from a contract. The row of a network's own coin, such as ETH, carries no contractAddress.

Every row lists in operations what it can take. A transfer on the asset's own network appears as direct_transfer settled by direct, on both kinds of row. A swap or a transfer to another network appears only where the row lists it, with the representations it can deliver in toAssetIds. A quote for an operation the row does not list is refused with 409 ROUTE_NOT_AVAILABLE before anything is priced. The test-balance endpoint grants only non-canonical-test tokens and answers ASSET_NOT_FUNDABLE for a canonical row. See Swaps and bridges for the operations of each row, the USDC route between Arbitrum Sepolia and Base Sepolia, and what to do with each refusal.

Three independent choices, not one mode

A deployment answers three separate questions, and mixing them into a single setting is what once let a change of execution path change which account the money came from:

  • Account model decides the wallet's address, and is fixed for the life of the account. EVM accounts are EIP-7702: the wallet's own EOA authorizes delegation to the approved account implementation, so it gains behaviour while keeping its address.
  • Execution protocol decides only how a command travels. ERC-4337 wraps it in a UserOperation through the EntryPoint; direct relayer broadcasts a validated transaction. Both drive the same account, at the same address, and a deployment can move between them without touching a balance. ERC-4337 with Paymaster sponsorship is the default; direct_relayer is the approved fallback.
  • Gas sponsorship decides who pays: the Paymaster, or the relayer. Neither has authority to move funds or change account configuration.

On the ERC-4337 path the sponsorship is not optional. A UserOperation here is always paid by the deployment's Paymaster: there is no self-funded mode in which the account pays its own gas, and there is nothing to send in a request to ask for one or to decline it. A deployment that defines no Paymaster refuses ERC-4337 execution rather than falling back to one that would, so what an integration meets in that case is a refusal and never a charge it did not expect. An account paying its own network fee is what the UTXO families do — Bitcoin and Cardano take it from the coins being spent — and that is a different execution path, not a variant of this one.

An operation that took the ERC-4337 path publishes its userOpHash — on the operation and on each of its steps and legs, alongside transactionHash. It is what a bundler, eth_getUserOperationReceipt and the EntryPoint's UserOperationEvent identify the execution by, and it is absent, not empty, on an operation that ran through the direct relayer instead. See Operations, quotes and states.

An address therefore never depends on how an operation is executed. Changing protocol or sponsorship never migrates an account, moves a balance or changes an address.

A send split across networks

Declared limitation Everything in this section describes the send that the instance which served the request executes. What is not met today: a split send's legs are held by that instance, so another instance's worker finds none and sends the whole amount as a single transfer on one network — a payment the accepted quote did not describe. The legs, the per-leg costs and the partial-failure retry below all presuppose legs that worker will not find.

When the network you name cannot cover the amount on its own but the networks together can, the platform splits the send into one same-chain transfer per network holding part of the balance. Nothing is bridged and no third party charges a fee: each leg leaves from the network its balance already sits on.

The sender sees one quote and one confirmation. That quote carries legs — the amount and fees per network — and a totalDebit equal to the sum of the legs. A quote without legs is a single transfer.

What a consumer has to know to render it correctly:

  • Cost, network and transaction are per leg. A split ran one transaction per network, each with its own gas and its own payer, so there is no single figure that describes it. transactions names each hash with the network it settled on; the operation's chainId and transactionHash name one network, which for a send that used several is the first of them. See Costs and platform accounts.
  • If one leg fails after another already settled, the operation is partial — never presented as completed. Nothing is reversed automatically, the ledger holds only what actually happened, and a retry executes only the failed legs.
  • destinationKind says what the destination is. An external_address will receive several transfers on several networks, irreversibly, and its owner is not part of the conversation: disclose that before the sender confirms. Declared limitation Several transfers is the shape the instance that served the request executes; another instance's worker finds no legs and sends the whole amount as one transfer on one network.

Insufficient balance is refused only when the sum across networks falls short too, and the refusal states the aggregate figures.

Safety boundaries

Network and asset manifests restrict what can be reached. A deployment must match its chain ID and contract bytecode before calls are made.

Declared limitation An ambiguous broadcast enters broadcast_unknown, and the operation is then re-admitted to execution from that state by a durable compare-and-set, which rebuilds and re-signs the transaction before submitting it again, so a second transfer is possible. The specification asks for the chain to be consulted about the earlier submission before anything is sent again, and a deployment does not guarantee that today.

See Security and key management and the Roadmap for current network availability.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • Transfers — Sending a token, or the network's own coin, from a user's wallet to another address. The operation is quoted before anybody confirms, signed at the gateway and sent, ends in a transaction hash that a public block explorer shows, and is reconciled against the chain's receipt and logs.

  • Swaps — Two assets on the same network are exchanged against a pool this deployment owns and prices, at a fixed rate rather than a market one, from the API, the SDK, the Sandbox and the conversational bot. The quote states what will be delivered before it is accepted. The swap executes and confirms; reconciling both of its assets against the chain is what is still being completed.

  • Sponsored gas with ERC-4337 and a Paymaster — A user sends a token without holding the network's native coin. The operation travels as an ERC-4337 UserOperation through the EntryPoint contract, and a Paymaster contract pays the gas. The operation reports the network cost it incurred and that the Paymaster paid it.

  • Arbitrum Sepolia via API, SDK and Sandbox — Arbitrum Sepolia is reachable from the API, the SDK and the Sandbox, with no funds at risk. This row states that the network is integrated; the row of each operation states whether it is complete.

  • Base Sepolia via API, SDK and Sandbox — Base Sepolia is reachable from the API, the SDK and the Sandbox, with no funds at risk. This row states that the network is integrated; the row of each operation states whether it is complete.

  • Mainnet for production deployments — Execution on EVM networks where the funds are real, for a Partner's production deployment: its manifest enables the networks, the contracts and the assets, after the security review and with limits, reconciliation, pause and rollback in place. It depends on the custody, security and operational capabilities listed in the other areas being finished first. Switching it on for a given Partner is a step of that Partner's onboarding.