This flow is not live yet. The shapes on this page are the contract we are building to; field names can still change before it opens. Today, a key trades on-chain from organisation wallets granted to it, which TetraFi signs for (Move stablecoins across chains).
At a glance
Before you begin
- An API key with Read quotes, Submit orders, Read orders, venue trading and signed requests; no organisation-wallet grant.
- An EVM wallet whose private key you hold, with USDC and some ETH for gas on Base; it need not be registered in TetraFi.
- Foundry’s
cast, or Node.js with viem, and a Base RPC endpoint to read fees.
Why you pay the gas
Why you pay the gas
You sign and pay for each transaction yourself; TetraFi never holds a key or a signing grant for the wallet. It checks each signed transaction against the step it prepared before relaying it.
Keep the private key out of code
Keep the private key out of code
The snippets read the key from
SIGNER_PRIVATE_KEY. Load it from your secret manager, or use a hardware or remote signer that signs the same transaction.1
Quote with your address
POST /api/v1/quotes with your address for Base in source.tradingWallets, keeping cross-chain quotes. Pick one whose next.kind is order and signing.mode is you.Request
Output shape of the quote you pick (shortened)
When step 1 is the deposit itself
When step 1 is the deposit itself
If the bridge already has your USDC allowance,
firstStep has purpose trade and the trade takes one step: skip step 4 below.2
Sign the approval
Check that
type is transaction and from is your address, then sign firstStep.transaction exactly as given, with its nonce (the step object).- cast
- viem
cast mktx signs without broadcasting, estimating gas and fees from --rpc-url; --gas-price and --priority-gas-price set them yourself.3
Order with it
POST /api/v1/orders with an Idempotency-Key (Retries and recovery) and minReceive, because the quote reads minReceiveRequired: true. TetraFi checks the signed approval against its step and the chain, then relays it.Request
Output shape while the approval confirms, then when the deposit is ready (shortened)
4
Sign and submit each step the order asks for
When
next.kind is sign, sign next.step the same way and send it to POST /api/v1/orders/{orderId}/steps/{stepId} with a new Idempotency-Key. Here it is the deposit, or a fresh step 1 if the chain moved. Sign whatever next.step holds; never resend a transaction signed for an earlier step.Request
5
Follow it until it ends
Read
GET /api/v1/orders/{orderId} until terminal is true (Order status). Do not wait for an order.updated webhook to find a signing step: act before next.step.signBy.Output shape when it ends (shortened)
If it does not go to plan
A fresh step 1, or a step not signed in time
A fresh step 1, or a step not signed in time
A fresh step 1 means the chain moved and nothing was relayed: sign
next.step and submit it on the step endpoint. A step not signed by its signBy ends the order unfilled; quote again. Every ending: How it ends.You would rather broadcast it yourself
You would rather broadcast it yourself
Broadcast the signed transaction, then submit
{"kind":"transactionHash","txHash":"0x…"}. TetraFi reads it from the chain and applies the same checks. SIGNING_TRANSACTION_NOT_FOUND (409) means the chain does not show it yet: retry with backoff.You decide not to go on
You decide not to go on
Submit
{"kind":"declined"} on the step endpoint: the order ends unfilled and the deposit is never sent. An approval already mined stays.A refusal
A refusal
TetraFi relayed nothing for that submission; earlier steps may already be on-chain. Every code: Step refusals.
Run the full script
Runs every step above with
cast; it signs and orders only with TETRAFI_PLACE_ORDER=1.Next
Sign with your own wallet
Every step type, submission kind and outcome.
How a trade runs
The other ways a trade is funded and signed.