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

# Canal User

> Recebendo atualizações sobre suas próprias ordens e transações

## Visão Geral

O canal `user` permite receber atualizações em tempo real sobre suas próprias ordens e transações. Este canal é útil para monitorar o status das suas ordens, receber notificações de execuções e acompanhar suas transações.

## Autenticação

O canal `user` **requer autenticação** usando sua chave de API (`X-Api-Key`). A chave deve ser fornecida no campo `auth` da mensagem de subscribe.

## Subscribe

Para se inscrever no canal user:

```json theme={null}
{
  "type": "subscribe",
  "channel": "user",
  "auth": "sua-chave-api-aqui"
}
```

### Requisitos

* **`auth`** (obrigatório): Sua chave de API (`X-Api-Key`)

<Warning>
  Mantenha sua chave de API segura e nunca a exponha em código cliente ou repositórios públicos.
</Warning>

## Mensagens Recebidas

### Atualização de Usuário

Recebida quando há mudanças nas suas ordens ou transações.

**Estrutura:**

```json theme={null}
{
  "trade_type": "order.filled",
  "order_id": 123,
  "user_id": "string",
  "event_id": "string",
  "market_id": "string",
  "side": "BUY",
  "contract_type": "YES",
  "price": 40,
  "quantity": 10,
  "transaction_fee": 10
}
```

### Campos

* **`trade_type`**: O que aconteceu com a ordem (`order.filled`, `order.partially_filled`, `order.placed`, `order.cancelled`);
* **`order_id`**: O ID da ordem;
* **`user_id`**: Seu ID de usuário;
* **`event_id`**: ID do evento relacionado;
* **`market_id`**: ID do mercado relacionado;
* **`side`**: Lado da ordem (`BUY` ou `SELL`);
* **`contract_type`**: Tipo de contrato (`YES` ou `NO`);
* **`price`**: Preço da transação em ticks;
* **`quantity`**: Quantidade de contratos;
* **`transaction_fee`**: Taxa de transação em centavos.

## Exemplo de Uso

<CodeGroup>
  ```javascript JavaScript theme={null}
  const ws = new WebSocket('wss://data-ws-dev.voxfi.com.br');
  const API_KEY = 'sua-chave-api-aqui';

  ws.onopen = () => {
    // Inscrever-se no canal user
    ws.send(JSON.stringify({
      type: 'subscribe',
      channel: 'user',
      auth: API_KEY
    }));
  };

  ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    
    if (data.user_id) {
      console.log('Atualização de usuário recebida:', data);
      
      // Processar atualização
      if (data.side === 'BUY') {
        console.log(`Compra executada: ${data.quantity} contratos ${data.contract_type} a ${data.price} ticks`);
      } else {
        console.log(`Venda executada: ${data.quantity} contratos ${data.contract_type} a ${data.price} ticks`);
      }
    }
  };
  ```

  ```python Python theme={null}
  import asyncio
  import websockets
  import json

  API_KEY = 'sua-chave-api-aqui'

  async def subscribe_user():
      uri = "wss://data-ws-dev.voxfi.com.br"
      
      async with websockets.connect(uri) as websocket:
          # Inscrever-se no canal user
          subscribe_msg = {
              "type": "subscribe",
              "channel": "user",
              "auth": API_KEY
          }
          await websocket.send(json.dumps(subscribe_msg))
          
          # Receber mensagens
          async for message in websocket:
              data = json.loads(message)
              
              if "user_id" in data:
                  print("Atualização de usuário recebida:", data)
                  
                  if data.get("side") == "BUY":
                      print(f"Compra executada: {data['quantity']} contratos {data['contract_type']} a {data['price']} ticks")
                  else:
                      print(f"Venda executada: {data['quantity']} contratos {data['contract_type']} a {data['price']} ticks")

  asyncio.run(subscribe_user())
  ```
</CodeGroup>

## Unsubscribe

Para cancelar a inscrição do canal user:

```json theme={null}
{
  "type": "unsubscribe",
  "channel": "user"
}
```

## Casos de Uso

* **Monitoramento de Ordens**: Receba notificações instantâneas quando suas ordens forem executadas;
* **Rastreamento de Transações**: Acompanhe todas as suas transações em tempo real;
* **Gerenciamento de Portfólio**: Atualize seu portfólio local conforme as transações ocorrem;
* **Alertas de Execução**: Implemente alertas quando ordens específicas forem preenchidas;
* **Análise de Performance**: Colete dados sobre suas transações para análise posterior.

## Boas Práticas

* **Segurança**: Nunca exponha sua chave de API em código cliente. Use variáveis de ambiente ou serviços de backend para gerenciar a autenticação;
* **Validação**: Sempre valide as mensagens recebidas antes de processá-las;
* **Logging**: Registre todas as atualizações recebidas para auditoria e debugging;
* **Tratamento de Erros**: Trate erros de autenticação adequadamente e implemente reconexão quando necessário.