Carteiras estáticas

Carteiras estáticas são endereços permanentes para receber pagamentos em criptomoedas. Elas são vinculadas a um order_id específico e são únicas pela combinação de project_id + order_id + currency + network.

Use carteiras estáticas para:

• Depósitos recorrentes do mesmo usuário
• Endereços de pagamento de longo prazo exibidos no perfil de um usuário
• Fluxos de depósito de alto volume em que se deseja um endereço estável por usuário

Criar carteira estática

Parâmetros da requisição

Exemplo de requisição

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

Exemplo de resposta

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

Informações da carteira

Obtenha informações da carteira estática por uuid ou address.

Parâmetros da requisição

Exemplo de resposta

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

• total_received — soma de todos os depósitos recebidos por esta carteira, em currency.
• transactions_count — número de depósitos recebidos até o momento.
• qr — data URI em base64 do QR code do endereço de depósito (sempre presente em carteiras estáticas, pois o endereço é atribuído na criação).

Lista de carteiras

Parâmetros da requisição

Exemplo de resposta

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

Habilitar / desabilitar carteira

Alterne se uma carteira estática aceita novos pagamentos.

Requisição

Ambos os endpoints recebem um único parâmetro:

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

Exemplo de resposta

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}

Para enable, status é "active" e message é "Static wallet enabled successfully".

Transações da carteira

Obtenha a lista de todos os depósitos recebidos por uma carteira estática.

Parâmetros da requisição

Exemplo de resposta

{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}

• fee_amount — taxa da plataforma deduzida deste depósito, em currency.
• net_amount — valor creditado no saldo do comerciante após a taxa.

Webhooks de carteiras estáticas

Quando um pagamento é recebido em uma carteira estática, o sistema envia um webhook para url_callback.

Payload do webhook

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "tx_explorer_url": "https://tronscan.org/#/transaction/8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

Referência de campos

Boas práticas

• order_id único — Use um order_id único para cada usuário ou pedido
• Idempotência — Verifique txid antes de processar para evitar créditos duplicados
• Verifique assinaturas — SEMPRE verifique a assinatura sign antes de creditar fundos
• Use merchant_amount — Credite usuários com base em merchant_amount, não em payment_amount

Ciclo de vida e idempotência

Uma carteira estática é uma identidade de depósito reutilizável, não uma fatura. Ela não tem valor esperado e não possui expiração. Um endereço pode gerar qualquer número de transações de depósito ao longo de sua vida útil.

A criação é idempotente para o mesmo projeto do comerciante, order_id, currency e network: a carteira existente é retornada. Mantenha essa tupla estável e persista a carteira retornada uuid; não use um novo order_id cada vez que o mesmo cliente abrir a tela de depósito.

A idempotência do depósito é diferente da idempotência da carteira:

• order_id identifica o mapeamento reutilizável carteira/cliente;
• carteira uuid identifica o registro permanente da carteira;
• webhook uuid identifica uma transação de depósito detectada;
• txid identifica a transferência on-chain e é a chave principal de deduplicação para crédito.

Use uma restrição de unicidade no banco de dados para a identidade processada chain/network/txid e reivindique-a na mesma transação que credita o saldo interno do cliente.

Habilitar e desabilitar semânticas

Desabilitar uma carteira impede que a aplicação a processe como um destino de depósito ativo; isso não apaga o endereço ou seu histórico e não pode impedir uma transferência blockchain já enviada por um usuário.

Reativar preserva a mesma identidade e endereço da carteira. Não crie uma substituição apenas para alterar o rótulo; rótulos não são identificadores de liquidação.

Casos de borda de carteira estática

Modelo de reconciliação

Execute um trabalho periódico que percorra /v1/static-wallet/transactions, atualize depósitos por txid e compare seus merchant_amount, status e resultado de conversão opcional com seu livro razão interno. A entrega via webhook deve tornar a reconciliação rápida, mas a reconciliação deve torná-la completa.