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

# Sign with your own wallet

> Trade on on-chain venues from a wallet whose key only you hold: TetraFi prepares each transaction, you sign it, TetraFi checks and relays it.

> [!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 ([Choose wallets and accounts](https://tetrafi.mintlify.site/trade/wallets-and-accounts.md)).

Name your wallet's address in the quote request, sign the step each on-chain quote carries, and send it with your order. You pay your own gas; TetraFi never holds a key or a signing grant for the wallet.

## At a glance

| Step | Call | What you get |
| - | - | - |
| Quote for your wallet | `POST /api/v1/quotes` with `source.tradingWallets` | On-chain quotes with `signing.firstStep` |
| Order with step 1 signed | `POST /api/v1/orders` with `firstStep` | The order; it opens and executes step 1 in one call |
| Sign a later step, if any | `POST /api/v1/orders/{orderId}/steps/{stepId}` | The order again |
| Follow | `GET /api/v1/orders/{orderId}` or [webhooks](https://tetrafi.mintlify.site/trade/webhooks.md) | `terminal: true` |

A trade takes two calls (quote, order) when the venue already has your token allowance, and three on a token's first trade: an approval, then the trade.

You need a key with [venue trading](https://tetrafi.mintlify.site/authentication.md#trade-on-your-venue-accounts), and no organisation-wallet grant. The wallet need not be registered first, unless your workspace lets keys trade only from wallets it approved (`SIGNING_WALLET_NOT_ALLOWED`): then get the address approved before you order.

## Trade from your wallet

The full walk-through, with `cast` and viem: [Move stablecoins from your own wallet](https://tetrafi.mintlify.site/recipes/own-wallet-trade.md).

**1. Quote with your address**

Send your wallet's address for its network in `source.tradingWallets`, and fix `sellAmount`. Exchange and OTC venues quote as usual.

**2. Sign the step**

Sign the quote's `signing.firstStep` ([the step object](#the-step-object)).

**3. Order with it**

`POST /api/v1/orders` with `firstStep`, an `Idempotency-Key`, and `minReceive` when the quote reads `minReceiveRequired: true`.

**4. Sign any later step**

While `next.kind` is `sign`, [submit](#submit-a-step) `next.step`, then follow the order until `terminal` is `true` ([Order status](https://tetrafi.mintlify.site/trade/order-status.md)).

## The step object

Each on-chain quote is firm for your address and carries the first step to sign in `signing.firstStep`; later steps arrive as the order's `next.step`.

```json Output shape on each on-chain quote (shortened) expandable theme={null}
"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": "0x…", "value": "0", "nonce": 17}
  }
}
```

Sign `transaction` on the chain of the step's `network` (`eip155:8453` is chain 8453), keeping its `nonce`; gas and fees are yours to set. Every venue at opening uses `transaction` steps; `typedData`, an EIP-712 message, comes with later venues.

> [accordion] What a step can be
>
> `type` is `transaction` or `typedData`; `purpose` is `approval`, `trade`, `revoke`, `acceptance` or `funding`. Both lists can grow: do not sign a `type` you do not know, and keep following the order.

> [accordion] Who signs
>
> `signing.mode` is `you` for an address TetraFi cannot sign for, and `tetrafi` for an organisation wallet granted to your key. Send `source.signer: "you"` to sign yourself for a wallet TetraFi could sign. The list of modes can grow.

> [accordion] Your wallet in TetraFi
>
> The address is screened before anything is relayed. Your first checked signature proves the wallet is yours: it then appears in Treasury as an external wallet, and an Owner can remove it. The output goes back to the signing wallet; delivery to another wallet of your workspace comes later.

> [accordion] Venues and networks at opening
>
> Uniswap, Across, Relay, Circle CCTP and Multiliquid on EVM networks, for a quote with `sellAmount`: with `buyAmount` these venues read `unavailable` (`exactOutputDeliveryUnsupported`). Other venues read `unavailable` (`clientSignedVenueUnsupported`). More venues, Solana and Tron follow as new step types.

## Submit a step

Step 1 goes in the order body as `firstStep`, with its `stepId`. A later step goes to `POST /api/v1/orders/{orderId}/steps/{stepId}` with a new `Idempotency-Key`; the body is the submission itself, without `quoteId` or `firstStep`: `{"kind":"signedTransaction","raw":"0x02f9…"}`. The answer is the order once its `next` has moved past the step, or after at most 15 seconds.

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

> [accordion] Submission kinds: signedTransaction, transactionHash, signature, declined
>
> | `kind` | Send | What TetraFi does |
> | - | - | - |
> | `signedTransaction` | `raw` | Checks it against the step it issued, then relays it and follows it on-chain. |
> | `transactionHash` | `txHash` | You broadcast it yourself; TetraFi checks it on-chain. |
> | `signature` | `signature` | For a `typedData` step: checks it, then passes it to the venue. |
> | `declined` | nothing | On the step endpoint only: ends the order `unfilled` and sends no further step. It does not undo a transaction already on-chain. |

## How it ends

If your wallet's nonce, allowance or balance changed between the quote and the order, or the `minReceive` you send changes the trade's transaction, nothing is relayed: the order opens and `next` carries a fresh first step to sign.

> [accordion] Endings: unsigned, reverted, nonce used
>
> | What happened | How the order reads |
> | - | - |
> | A later step was not signed by `signBy` | `unfilled`, `outcomeCode: not_sent`. A mined approval stays. |
> | A step's transaction reverted | `unfilled` or `failed`, with the reason. |
> | Another transaction used the step's nonce | `unfilled`, `outcomeCode: nonce_used_elsewhere`. |

### Step refusals

TetraFi relayed nothing for the submission it refused. Earlier steps may already be on-chain, as may a transaction you broadcast yourself: read the order and its step hashes before you retry.

> [accordion] Every step refusal
>
> | Code | Status | Meaning |
> | - | - | - |
> | `SIGNING_STEP_REQUIRED` | 422 | An order on a `you` quote without `firstStep`. |
> | `SIGNING_STEP_MISMATCH` | 422 | The signed step differs from the one issued; `details.field` says where. |
> | `SIGNING_STEP_NOT_OPEN` | 409 | Already answered, or the order no longer waits for it; nothing was sent. Read the order for its next step. |
> | `SIGNING_STEP_EXPIRED` | 410 | Past its `signBy`; nothing was sent. Read the order for how it ended. |
> | `SIGNING_TRANSACTION_NOT_FOUND` | 409 | The chain does not show the transaction yet: retry shortly. |
> | `SIGNING_WALLET_SCREENING_PENDING` | 409 | The wallet's screening is still running: retry shortly. |
> | `SIGNING_WALLET_REFUSED` | 403 | The address failed screening. |
> | `SIGNING_STEP_REFUSED` | 403 | The key may not trade from this wallet now; the message says why. |
> | `SIGNING_WALLET_NETWORK_UNSUPPORTED` | 422 | No venue trades the wallet's network here, or its wallets cannot sign their own trades yet (only EVM networks can). No venue was asked. |
> | `SIGNING_WALLET_NOT_ALLOWED` | 403 | Only an API key names such a wallet, your workspace may not let keys trade from wallets it has not approved, or another organisation proved the address. No venue was asked. |

## What comes next

> [accordion] Planned signing modes, step types and venues
>
> Planned, and not available yet:
>
> * People approve one trade: `signing.mode` `owners` (your wallet's owners approve the trade) and `custodian` (your custodian's own approvers do). The order's `next.kind` is then `approve`, with an `approvalUrl` where they approve it: the same pattern [wallet creation](https://tetrafi.mintlify.site/trade/wallets-and-accounts.md#create-a-wallet) uses.
> * Solana and Tron, as new step `type` values.
> * Bebop and StableFX from your own wallet. StableFX takes two signed messages and its quote lasts about 4 seconds, so only an automated signer keeps up.
> * Custody wallets that TetraFi signs for, as `signing.mode` `tetrafi`.
>
> Build for them now: ignore a `signing.mode`, step `type`, `purpose`, submission `kind` or `next.kind` you do not know, never sign a step `type` you do not know, and keep following the order until `terminal` is `true`.

## Next

> [card] [Choose wallets and accounts](https://tetrafi.mintlify.site/trade/wallets-and-accounts.md)
>
> Every source a quote can trade from.

> [card] [Order status](https://tetrafi.mintlify.site/trade/order-status.md)
>
> Follow the order to the end.

> [card] [Recipe: move stablecoins from your own wallet](https://tetrafi.mintlify.site/recipes/own-wallet-trade.md)
>
> An approval, then a bridge deposit, signed with a local key.

> [card] [How a trade runs](https://tetrafi.mintlify.site/trade/how-a-trade-runs.md)
>
> Every way a trade is funded, signed and settled.


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