> ## Documentation Index
> Fetch the complete documentation index at: https://tetrafi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Move stablecoins from your own wallet

> Move USDC from Base to Ethereum from a wallet whose key only you hold: quote with its address, sign the approval and the deposit with a local key, and follow the order to the end.

> [!NOTE]
>
> 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](https://tetrafi.mintlify.site/recipes/cross-chain-stablecoins.md)).

Move 100 USDC from Base to Ethereum through a bridge, from a wallet you sign for yourself. The first trade on a token takes two steps: an approval, then the deposit.

## At a glance

| | |
| - | - |
| You trade | 100 USDC on Base (`eip155:8453`) for USDC on Ethereum (`eip155:1`). |
| Endpoints | `POST /api/v1/quotes`, `POST /api/v1/orders`, `POST /api/v1/orders/{orderId}/steps/{stepId}`, `GET /api/v1/orders/{orderId}`. |
| You sign | Step 1, the token approval; step 2, the bridge deposit. Each is one EVM transaction. |
| Result | A finished order, with both transaction hashes under `operation.steps`. |

```mermaid theme={null}
flowchart LR
  A[Quote with your address] --> B[Sign the approval]
  B --> C[Order with it]
  C --> D[Sign the deposit]
  D --> E[Submit it]
  E --> F[Follow to terminal]
```

## Before you begin

* An API key with Read quotes, Submit orders, Read orders, [venue trading](https://tetrafi.mintlify.site/authentication.md#trade-on-your-venue-accounts) and [signed requests](https://tetrafi.mintlify.site/authentication.md#sign-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](https://getfoundry.sh)'s `cast`, or Node.js with [viem](https://viem.sh), and a Base RPC endpoint to read fees.

> [accordion] 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.

> [accordion] 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.

> [!WARNING]
>
> This recipe moves funds out of your wallet once it is live.

**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`.

```json Request theme={null}
{"kind":"pair","sell":{"asset":"USDC","network":"eip155:8453"},"buy":{"asset":"USDC","network":"eip155:1"},"sellAmount":"100",
 "filters":{"locations":["crossChain"]},
 "source":{"tradingWallets":{"eip155:8453":"0xAbc…"}}}
```

```json Output shape of the quote you pick (shortened) expandable theme={null}
{
  "id": "q_01M5…",
  "next": {"kind": "order"},
  "minReceiveRequired": true,
  "signing": {
    "mode": "you",
    "address": "0xAbc…",
    "firstStep": {
      "stepId": "3f2b9c1e-8d4a-4c7e-9b1f-…",
      "sequence": 1,
      "purpose": "approval",
      "type": "transaction",
      "network": "eip155:8453",
      "from": "0xAbc…",
      "signBy": "2026-11-18T12:00:45Z",
      "transaction": {"to": "0x…", "data": "0x095ea7b3…", "value": "0", "nonce": 17}
    }
  }
}
```

> [accordion] 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](https://tetrafi.mintlify.site/trade/sign-with-your-own-wallet.md#the-step-object)).

> [tab] cast
>
> ```bash theme={null}
> # step holds firstStep (or a later next.step) as JSON
> tx=$(jq -c '.transaction' <<<"$step")
> raw=$(cast mktx "$(jq -r .to <<<"$tx")" "$(jq -r .data <<<"$tx")" \
>   --chain "$(jq -r '.network | split(":")[1]' <<<"$step")" \
>   --nonce "$(jq -r .nonce <<<"$tx")" \
>   --value "$(jq -r .value <<<"$tx")" \
>   --rpc-url "$BASE_RPC_URL" \
>   --private-key "$SIGNER_PRIVATE_KEY")
> ```
>
> `cast mktx` signs without broadcasting, estimating gas and fees from `--rpc-url`; `--gas-price` and `--priority-gas-price` set them yourself.

> [tab] viem
>
> ```ts theme={null}
> import { createPublicClient, http, type Address, type Hex } from 'viem';
> import { privateKeyToAccount } from 'viem/accounts';
> import { base } from 'viem/chains';
>
> type TransactionStep = {
>   stepId: string;
>   type: string;
>   network: string; // CAIP-2, e.g. eip155:8453
>   from: Address;
>   transaction: { to: Address; data: Hex; value: string; nonce: number };
> };
>
> const account = privateKeyToAccount(process.env.SIGNER_PRIVATE_KEY as Hex);
> const client = createPublicClient({ chain: base, transport: http(process.env.BASE_RPC_URL) });
>
> export async function signStep(step: TransactionStep): Promise<Hex> {
>   if (step.type !== 'transaction') throw new Error(`Unknown step type ${step.type}: do not sign it`);
>   if (step.from.toLowerCase() !== account.address.toLowerCase()) throw new Error('Step is for another wallet');
>   const tx = step.transaction;
>   const fees = await client.estimateFeesPerGas(); // gas and fees are your choice
>   const gas = await client.estimateGas({ account, to: tx.to, data: tx.data, value: BigInt(tx.value) });
>   return account.signTransaction({
>     chainId: Number(step.network.split(':')[1]),
>     to: tx.to,
>     data: tx.data,
>     value: BigInt(tx.value),
>     nonce: tx.nonce, // pinned: sign with it
>     gas,
>     maxFeePerGas: fees.maxFeePerGas,
>     maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
>   });
> }
> ```

**3. Order with it**

`POST /api/v1/orders` with an `Idempotency-Key` ([Retries and recovery](https://tetrafi.mintlify.site/trade/orders.md#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.

```json Request theme={null}
{"quoteId":"q_01M5…","minReceive":"99.45","firstStep":{"stepId":"3f2b9c1e-8d4a-4c7e-9b1f-…","kind":"signedTransaction","raw":"0x02f8…"}}
```

```json Output shape while the approval confirms, then when the deposit is ready (shortened) expandable theme={null}
{"orderId":"9410e38e-…","status":"working","terminal":false,"next":{"kind":"wait","retryAfter":"PT5S"}}
{"orderId":"9410e38e-…","status":"working","terminal":false,
 "next":{"kind":"sign","step":{"stepId":"7a41d0e5-2c6b-4f39-a8e2-…","sequence":2,"purpose":"trade","type":"transaction","network":"eip155:8453","from":"0xAbc…","signBy":"2026-11-18T12:02:10Z",
   "transaction":{"to":"0x…","data":"0x…","value":"0","nonce":18}}}}
```

**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.

```json Request theme={null}
{"kind":"signedTransaction","raw":"0x02f9…"}
```

**5. Follow it until it ends**

Read `GET /api/v1/orders/{orderId}` until `terminal` is `true` ([Order status](https://tetrafi.mintlify.site/trade/order-status.md)). Do not wait for an `order.updated` webhook to find a signing step: act before `next.step.signBy`.

```json Output shape when it ends (shortened) expandable theme={null}
{"orderId":"9410e38e-…","status":"settled","terminal":true,
 "operation":{"steps":[
   {"stepId":"3f2b9c1e-8d4a-4c7e-9b1f-…","purpose":"approval","status":"mined","txHash":"0x5e1…"},
   {"stepId":"7a41d0e5-2c6b-4f39-a8e2-…","purpose":"trade","status":"mined","txHash":"0x9c4…"}]}}
```

## If it does not go to plan

> [accordion] 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](https://tetrafi.mintlify.site/trade/sign-with-your-own-wallet.md#how-it-ends).

> [accordion] 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.

> [accordion] 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.

> [accordion] A refusal
>
> TetraFi relayed nothing for that submission; earlier steps may already be on-chain. Every code: [Step refusals](https://tetrafi.mintlify.site/trade/sign-with-your-own-wallet.md#step-refusals).

> [card] [Run the full script](https://github.com/TetraFi/docs/blob/main/samples/http/recipe-own-wallet.sh)
>
> Runs every step above with `cast`; it signs and orders only with `TETRAFI_PLACE_ORDER=1`.

## Next

> [card] [Sign with your own wallet](https://tetrafi.mintlify.site/trade/sign-with-your-own-wallet.md)
>
> Every step type, submission kind and outcome.

> [card] [How a trade runs](https://tetrafi.mintlify.site/trade/how-a-trade-runs.md)
>
> The other ways a trade is funded and signed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.