<!-- tempo-docs-context -->
> Source: [/docs/zones/withdraw](https://tempo.com/developers/docs/zones/withdraw.md)
> Section: [Zones](https://tempo.com/developers/docs/zones.md). Connect to a Zone and work with private balances, deposits, and withdrawals. Zones is live on Mainnet; see the introduction to set up a Zone. Earlier testnet sandbox guides describe a separate integration.
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

<span id="withdraw-from-a-zone" />

# Withdraw From a Zone

Withdraw through the Zone's outbox, then track delivery to a Tempo recipient.

## Overview

A withdrawal moves funds from a [Zone](https://tempo.com/developers/docs/zones), a private stablecoin ledger, back to a recipient on Tempo. You submit it to the Zone's outbox (`ZoneOutbox`), a contract that burns the Zone-side tokens and queues the withdrawal. The sequencer, which orders Zone blocks, groups queued withdrawals into a batch. The Zone's portal (`ZonePortal`), which holds the backing assets on Tempo, accepts the batch and releases the tokens.

So the source transaction, the accepted batch, and the recipient's token receipt are three separate events. Track each one.

This page uses an authenticated Zone RPC connection and the deployment details from [Connect to a Zone](https://tempo.com/developers/docs/zones/connect): the Zone ID, chain ID, and outbox and portal addresses.

<span id="submit-and-track-a-withdrawal" />

## Setup

<span id="check-the-destination-and-access-rules" />

:::steps
### Prepare the Withdrawal

Confirm the token, amount, Tempo recipient, and fallback recipient with the operator's tooling. The fallback recipient (`zoneFallbackRecipient`) is a Zone account that gets the funds back if delivery on Tempo fails. Confirm that the deployment's funding rules permit the token, the recipient, and any callback.

A callback is a contract call on Tempo that runs with the withdrawal, such as a swap. If you use one, confirm the target and its callback interface before you sign. A portal can restrict callbacks to registered targets, which is called gateway enforcement. Then the portal admin must grant the target the `CallbackGateway` role.

<span id="include-withdrawal-fees" />

#### Calculate Withdrawal Fees

Read `calculateWithdrawalFee(gasLimit)` from the deployed outbox. `gasLimit` is the gas you reserve for a callback, and `0` for a plain withdrawal. Reserve this fee and the Zone transaction fee on top of the amount withdrawn. The [withdrawal fee rules](https://tempo.com/developers/docs/protocol/zones/execution#withdrawal-fees) define the calculation.

<span id="submit-through-the-zone-outbox" />

<span id="request-a-withdrawal" />

### Submit the Withdrawal

Submit the withdrawal to the outbox with the SDK or contract interface the operator supports for your deployment. Interfaces differ between deployments. Save the source transaction hash and the withdrawal's `senderTag`. Tempo shows the `senderTag` instead of the sender's address, which keeps the sender private. You use it to look up the withdrawal in [Track the Withdrawal](https://tempo.com/developers/docs/zones/withdraw#track-the-withdrawal). Its [derivation](https://tempo.com/developers/docs/protocol/zones/bridging#verifiable-withdrawals) uses the sender, the transaction hash, and a per-withdrawal `fallbackNonce`.

<span id="track-settlement-on-tempo" />

<span id="track-delivery" />

### Confirm Delivery

The sequencer includes the withdrawal in a batch. The portal accepts the batch, then processes the withdrawal and transfers the tokens on Tempo. Keep it pending until the recipient's delivery is confirmed, as [Track the Withdrawal](https://tempo.com/developers/docs/zones/withdraw#track-the-withdrawal) describes.
:::

<span id="read-the-withdrawal-status" />

## Track the Withdrawal

Read Tempo outcomes with the hosted [Zone withdrawal status API](https://tempo.com/developers/docs/api/zones), part of the Tempo API. It looks up withdrawals by `senderTag` and returns each processed withdrawal in `data`. Use the tag of this withdrawal, since withdrawals in one transaction can have different tags.

Each outcome has two status fields:

* **`status`:** `completed` or `failed`, for delivery on Tempo. `transactionHash` is the Tempo transaction that processed the withdrawal.
* **`zoneStatus`:** `completed` once the Zone has proven it imported the Tempo block that processed the withdrawal. It says nothing about delivery or a refund.

The API needs a Tempo API key with `data:read` and access to that Zone, created in [Tempo Console](https://tempo.com/developers/docs/api/authentication#api-keys). In the playground, select **Try**. Enter the `senderTag` and the Zone's numeric `chainId` from the operator. The request tool includes language examples and the response.

`GET /v1/zones/withdrawals/{senderTag}`

List Zone withdrawals

[API reference](https://tempo.com/developers/docs/api/zones#listzonewithdrawals) — request parameters, authentication, and response schema. The examples below use editable sample values.

Requires a [Tempo API key](https://tempo.com/developers/docs/api/console/api-keys). Replace `YOUR_API_KEY` before running this request.

**cURL**

```bash
curl 'https://api.tempo.xyz/v1/zones/withdrawals/0x61fc42a734cb44acef497ea0bed612c691195623244136e0739e1929569e2487?chainId=1424310003' \
  --header 'tempo-api-key: YOUR_API_KEY'
```

**TypeScript**

```ts
fetch('https://api.tempo.xyz/v1/zones/withdrawals/0x61fc42a734cb44acef497ea0bed612c691195623244136e0739e1929569e2487?chainId=1424310003', {
  headers: {
    'tempo-api-key': 'YOUR_API_KEY'
  }
})
```

An empty `data` array means no outcome is indexed yet. Keep the withdrawal pending until `status` is `completed`, or until a `failed` withdrawal's funds return to the fallback recipient, as [Handle Withdrawal Failures](https://tempo.com/developers/docs/zones/withdraw#handle-withdrawal-failures) describes.

<span id="handle-failed-delivery" />

<span id="handle-refunds" />

## Handle Withdrawal Failures

A withdrawal fails when its token transfer or callback reverts on Tempo, such as from a token pause or a TIP-403 policy. The portal then bounces back the funds, which means it deposits them into the source Zone again, to the fallback recipient. The withdrawal fee isn't refunded.

The bounce-back is a deposit, so the sequencer processes it like any other. If a policy or pause blocks minting in the Zone, the inbox (`ZoneInbox`) records a pending refund instead. The fallback recipient claims it with `ZoneInbox.claimRefund(token)` once minting is permitted. [Withdrawal failure and bounce-back](https://tempo.com/developers/docs/protocol/zones/bridging#withdrawal-failure-and-bounce-back) covers each case.

## Call a Contract on Tempo

A withdrawal with a callback calls a contract on Tempo through `ZoneMessenger`, subject to the deployment's access rules. The token transfer and the call succeed or revert together. If the call deposits into a Zone, that Zone credit settles separately, after the Tempo call. The [composable withdrawal specification](https://tempo.com/developers/docs/protocol/zones/bridging#composable-withdrawals) defines the callback interface and limits.

<span id="try-a-sandbox-withdrawal" />

## Related

[Bridging](https://tempo.com/developers/docs/protocol/zones/bridging): Covers withdrawals, composable callbacks, and bounce-back refunds.

[Withdraw OUSD](https://tempo.com/developers/docs/guide/private-zones/withdraw-from-a-zone): Use for trying a withdrawal with OUSD test funds in the testnet sandbox.

[Balances and Activity](https://tempo.com/developers/docs/zones/balances): Use for reading the private balance before and after a withdrawal.

[Deposit Into a Zone](https://tempo.com/developers/docs/zones/deposit): Use for funding a private account through the portal on Tempo.
