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

# user_trades

> Subscribe to real-time trade notifications when your orders are matched

When orders match, this topic notifies the users involved in the match process. Buyer and seller will get notified about what orders were executed.

<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 `user_trades`

  Example: `["user_trades"]`
</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 `user_trades`)
</ResponseField>

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

<ResponseField name="body" type="object">
  Trade execution details

  <Expandable title="Trade Details">
    <ResponseField name="user_id" type="string">
      Your user ID
    </ResponseField>

    <ResponseField name="trade" type="object">
      Trade information object

      <Expandable title="Trade Information">
        <ResponseField name="id" type="string">
          Trade identifier
        </ResponseField>

        <ResponseField name="amount" type="number">
          Amount executed in the base currency
        </ResponseField>

        <ResponseField name="price" type="number">
          Price per unit at which the trade executed
        </ResponseField>

        <ResponseField name="total_value" type="number">
          Total value of the trade (amount × price)
        </ResponseField>

        <ResponseField name="side" type="string">
          Your side in the trade: `buy` or `sell`
        </ResponseField>

        <ResponseField name="taker_or_maker" type="string">
          Your role in the trade: `taker` or `maker`
        </ResponseField>

        <ResponseField name="type" type="string">
          Your order type (e.g., `limit`, `market`)
        </ResponseField>

        <ResponseField name="fee" type="number">
          Trading fee charged for this trade
        </ResponseField>

        <ResponseField name="fee_currency" type="string">
          Currency in which fee was charged
        </ResponseField>

        <ResponseField name="pair_code" type="string">
          Trading pair code (e.g., ETH\_BRL)
        </ResponseField>

        <ResponseField name="your_order_id" type="string">
          Your order ID (use maker\_order\_id or taker\_order\_id)
        </ResponseField>

        <ResponseField name="maker_order_id" type="string">
          Order ID of the maker (liquidity provider)
        </ResponseField>

        <ResponseField name="taker_order_id" type="string">
          Order ID of the taker (liquidity taker)
        </ResponseField>

        <ResponseField name="date" type="string">
          Trade execution datetime (ISO 8601 format)
        </ResponseField>

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

## Subscription Example

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

## Stream Response Example - You as Taker

```json theme={null}
{
  "id": 9,
  "topic": "user_trades",
  "timestamp": 1673271591764,
  "body": {
    "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7",
    "trade": {
      "id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
      "amount": 1,
      "price": 49,
      "total_value": 49,
      "side": "buy",
      "taker_or_maker": "taker",
      "type": "market",
      "fee": 0,
      "fee_currency": "BCH",
      "pair_code": "BCH_BRL",
      "maker_order_id": "AF1C3AD2-D5A2-41CC-9A4C-646B600F9E01",
      "taker_order_id": "52B46D87-86A1-4978-B141-4E18E3E47514",
      "date": "2023-01-09T13:39:24.057Z",
      "timestamp": 1675780847920
    }
  }
}
```

## Stream Response Example - You as Maker

```json theme={null}
{
  "id": 10,
  "topic": "user_trades",
  "timestamp": 1673271591764,
  "body": {
    "user_id": "30B8CDBB-BDBD-4B60-A90F-860AB46B76F7",
    "trade": {
      "id": "08799ECC-F6B1-498E-B89C-2A05E6A181B9",
      "amount": 1,
      "price": 49,
      "total_value": 49,
      "side": "sell",
      "taker_or_maker": "maker",
      "type": "limit",
      "fee": 0.05,
      "fee_currency": "BCH",
      "pair_code": "BCH_BRL",
      "maker_order_id": "AF1C3AD2-D5A2-41CC-9A4C-646B600F9E01",
      "taker_order_id": "52B46D87-86A1-4978-B141-4E18E3E47514",
      "date": "2023-01-09T13:39:24.057Z",
      "timestamp": 1675780847920
    }
  }
}
```

## Maker vs Taker Explained

### Taker

* Your incoming order matched with an existing order in the book
* Usually pays higher fees
* Typically executed immediately

### Maker

* Your order was already in the order book
* Usually receives better fees
* Waited for another order to match

## Key Fields

| Field                | Description                        |
| -------------------- | ---------------------------------- |
| **amount**           | How much was traded                |
| **price**            | At what price it was executed      |
| **fee**              | Commission charged                 |
| **side**             | Whether you were buying or selling |
| **taker\_or\_maker** | Your role in this trade            |
| **total\_value**     | amount × price                     |

## Fee Implications

* **Maker**: Often lower fees (liquidity provider)
* **Taker**: Often higher fees (market taker)
* **Fee Currency**: May be different from trade pair
* **Fee Rebates**: Some exchanges offer maker rebates

## Calculation Examples

```javascript theme={null}
// Net proceeds after fees (for sell)
const netProceeds = trade.total_value - trade.fee;

// Cost including fees (for buy)
const costWithFees = trade.total_value + trade.fee;

// Fee percentage
const feePercent = (trade.fee / trade.total_value) * 100;

// Average execution price including fees
const avgPriceWithFees = (trade.total_value + trade.fee) / trade.amount;
```

## Usage Notes

* **Authentication Required**: Requires valid ticket from WebSocket authentication
* **Real-time Updates**: Receive immediate notification when your trades execute
* **Both Sides**: You get notified whether you're buyer or seller
* **Order Correlation**: Link trades back to your orders
* **Fee Information**: Complete fee details included
* **Timestamp**: Use for accurate trade recording

## You Receive Notifications For

* Trades where your market order hit existing orders
* Trades where your limit order was matched
* Both partial and full fills of your orders
* Trades from any of your active orders

## Use Cases

* **Trade Recording**: Record all trades in real-time
* **P\&L Tracking**: Calculate profit/loss as trades execute
* **Fee Accounting**: Track fees paid per trade
* **Order Confirmation**: Verify order fills
* **Automated Trading**: React to trade fills
* **Reporting**: Generate trade reports automatically
* **Reconciliation**: Reconcile with exchange records