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

# withdrawal

> Subscribe to real-time notifications of withdrawal events for your account

This topic is responsible for notifying the user when a fiat or cryptocurrency withdrawal occurs.

<Warning>
  This is an authenticated stream. You must provide a valid ticket from authentication to subscribe.
</Warning>

## Subscription Request

<ParamField body="method" type="string" required>
  Subscribe method. Must be `subscribe`
</ParamField>

<ParamField body="topics" type="array" required>
  Array of topics to subscribe to. Must include `withdrawal`

  Example: `["withdrawal"]`
</ParamField>

<ParamField body="ticket" type="string" required>
  Ticket created using the endpoint POST [https://api.ripio.com/trade/ticket](https://api.ripio.com/trade/ticket)
</ParamField>

## Stream Response

<ResponseField name="id" type="integer">
  Each WebSocket message includes a sequential numeric id. Each topic has its own unique sequence, and for private topics, the sequence is unique to each topic and user. It's important to note that some topics will send a "welcome message", which will have an id value of -1. Additionally, this sequence may be reset between connections, so be sure to update this value locally whenever you reconnect.
</ResponseField>

<ResponseField name="topic" type="string">
  Topic name (always `withdrawal`)
</ResponseField>

<ResponseField name="timestamp" type="integer">
  Timestamp in milliseconds
</ResponseField>

<ResponseField name="body" type="object">
  Withdrawal details object

  <Expandable title="Withdrawal Details">
    <ResponseField name="id" type="string">
      Withdrawal identifier
    </ResponseField>

    <ResponseField name="user_id" type="string">
      Your user ID
    </ResponseField>

    <ResponseField name="amount" type="number">
      Withdrawal amount
    </ResponseField>

    <ResponseField name="currency_code" type="string">
      Currency code (e.g., ETH, BTC, BRL)
    </ResponseField>

    <ResponseField name="status" type="string">
      Withdrawal status: `pending`, `confirmed`, `failed`
    </ResponseField>

    <ResponseField name="is_internal" type="boolean">
      Whether this is an internal transfer between BitcoinTrade accounts
    </ResponseField>

    <ResponseField name="destination_address" type="string">
      Destination address where funds are being sent
    </ResponseField>

    <ResponseField name="hash" type="string">
      Transaction hash on blockchain (once sent)
    </ResponseField>

    <ResponseField name="network" type="string">
      Blockchain network (e.g., bitcoin, ethereum, bitcoincash)
    </ResponseField>

    <ResponseField name="fee" type="number">
      Withdrawal fee charged by BitcoinTrade
    </ResponseField>

    <ResponseField name="miner_fee" type="number">
      Network miner fee (for blockchain withdrawals)
    </ResponseField>

    <ResponseField name="external_id" type="string">
      External identifier (if provided)
    </ResponseField>

    <ResponseField name="create_date" type="string">
      Withdrawal creation datetime (ISO 8601 format)
    </ResponseField>

    <ResponseField name="update_date" type="string">
      Last update datetime (ISO 8601 format)
    </ResponseField>
  </Expandable>
</ResponseField>

## Subscription Example

```json theme={null}
{
  "method": "subscribe",
  "topics": [
    "withdrawal"
  ],
  "ticket": "97794B95-AFE7-454F-81B0-9109112548C2"
}
```

## Stream Response Example - Cryptocurrency Withdrawal

```json theme={null}
{
  "id": 11,
  "topic": "withdrawal",
  "timestamp": 1673271591764,
  "body": {
    "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
    "user_id": "5B6A43AE-8012-402D-966F-87CF64689535",
    "amount": 100,
    "currency_code": "ETH",
    "status": "confirmed",
    "is_internal": false,
    "destination_address": "mpe8FKtvDktBN1FGToFpYN2pdktySxD8wg",
    "hash": "0x79704c92b31061b8f51e26486d6454aff3e3c58aa0d51f0f803d6fd063be8100",
    "network": "bitcoin",
    "fee": null,
    "miner_fee": null,
    "external_id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
    "create_date": "2023-01-09T13:39:24.057Z",
    "update_date": "2023-01-09T13:39:24.057Z"
  }
}
```

## Stream Response Example - Fiat Withdrawal

```json theme={null}
{
  "id": 12,
  "topic": "withdrawal",
  "timestamp": 1673271591764,
  "body": {
    "id": "2B222F22-5235-45FA-97FC-E9DBFA2575EE",
    "user_id": "5B6A43AE-8012-402D-966F-87CF64689535",
    "amount": 5000,
    "currency_code": "BRL",
    "status": "confirmed",
    "is_internal": true,
    "destination_address": null,
    "hash": null,
    "network": null,
    "fee": 0,
    "miner_fee": null,
    "external_id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
    "create_date": "2023-01-09T13:39:24.057Z",
    "update_date": "2023-01-09T13:39:24.057Z"
  }
}
```

## Withdrawal Status Lifecycle

```
pending → confirmed
    ↓
  failed
```

* **pending**: Withdrawal request created but not yet processed
* **confirmed**: Withdrawal sent and confirmed
* **failed**: Withdrawal failed and was not sent

## Withdrawal Types

### External Withdrawals

* To external blockchain addresses
* Requires blockchain confirmation
* Include miner fees
* Network dependent timing
* Bitcoin: \~10 minutes (6 confirmations)
* Ethereum: \~2 minutes (12 confirmations)

### Internal Transfers

* Between BitcoinTrade accounts
* No blockchain involved
* No miner fees
* Confirm immediately
* Marked with `is_internal: true`

## Fee Structure

### Platform Fee

* BitcoinTrade withdrawal fee
* Shown in `fee` field
* May vary by currency
* Deducted from withdrawal

### Network Fee

* Blockchain miner fee
* Shown in `miner_fee` field
* For external withdrawals only
* Varies with network congestion

### Total Cost

Total deducted = Platform fee + Miner fee

## Key Fields

| Field            | Description               |
| ---------------- | ------------------------- |
| **amount**       | Withdrawal amount         |
| **fee**          | BitcoinTrade fee          |
| **miner\_fee**   | Network miner fee         |
| **status**       | Current state             |
| **hash**         | Blockchain transaction ID |
| **is\_internal** | Internal transfer flag    |

## Blockchain Networks

| Network      | Code        | Currency |
| ------------ | ----------- | -------- |
| Bitcoin      | bitcoin     | BTC      |
| Ethereum     | ethereum    | ETH      |
| Bitcoin Cash | bitcoincash | BCH      |
| And others   | -           | -        |

## Timing by Currency

| Currency | Type     | Typical Confirmation |
| -------- | -------- | -------------------- |
| BTC      | External | 10-30 minutes        |
| ETH      | External | 2-5 minutes          |
| BCH      | External | 3-10 minutes         |
| BRL      | Internal | Immediate            |
| Others   | Variable | Variable             |

## Calculation Examples

```javascript theme={null}
// Net amount after fees
const netAmount = withdrawal.amount - withdrawal.fee - (withdrawal.miner_fee || 0);

// Total deducted from balance
const totalDeducted = withdrawal.amount;

// Fee percentage
const feePercent = ((withdrawal.fee + (withdrawal.miner_fee || 0)) / withdrawal.amount) * 100;
```

## Usage Notes

* **Authentication Required**: Requires valid ticket from WebSocket authentication
* **Real-time Updates**: Receive notification when withdrawal is processed
* **Multiple Notifications**: Receive updates as status changes (pending → confirmed)
* **Network Variable**: Confirmation time depends on blockchain network
* **Fee Information**: Both platform and miner fees shown

## Pending vs Confirmed

* **Pending**: Withdrawal submitted but not yet on blockchain
* **Confirmed**: Transaction sent to blockchain and confirmed
* **Recommended**: Wait for confirmed status before considering funds received

## Use Cases

* **Fund Tracking**: Monitor outgoing funds
* **Balance Updates**: Update balance when withdrawal completes
* **Withdrawal Confirmation**: Confirm withdrawal success
* **Fee Accounting**: Record fees paid
* **Transaction History**: Build withdrawal history
* **Compliance**: Track all withdrawals for reporting