Carteiras

Uma carteira informa ao gateway onde uma loja recebe pagamentos em uma rede no processamento somente de observação: o gateway deriva um endereço novo por intenção de pagamento a partir da sua chave pública estendida, de modo que os pagamentos vão direto para endereços que você controla e cada transferência corresponde, sem ambiguidade, a uma intenção.

Pagamentos live não usam carteiras de recebimento

Esta plataforma não usa o processamento somente de observação para pagamentos. Os pagamentos live são processados pela conta Bitcart da plataforma: os clientes pagam para as carteiras da plataforma e o FeitPay mantém os fundos em seu nome como um saldo em custódia, que você saca por meio de saques para endereços da lista de permitidos. Você não precisa de uma carteira de recebimento para aceitar pagamentos. Veja Custódia.

Nunca envie chaves privadas

O FeitPay só precisa de uma chave pública estendida. Ele nunca vai pedir uma chave privada, uma frase-semente ou um arquivo de carteira. Se alguma interface pedir isso a você, pare e denuncie.

POST/v1/walletslive · após ativação da conta

Cadastro de uma carteira somente de observação

Cadastre uma chave pública estendida (mode: "xpub") para uma rede que o registro liste como utilizável no seu ambiente. Uma rede que não esteja utilizável é recusada com network_unavailable.

{
  "store_id": "store_01J…",
  "network_id": "bitcoin:mainnet",
  "label": "Treasury (watch-only)",
  "mode": "xpub",
  "xpub": "zpub…",
  "gap_limit": 20
}

• Bitcoin: uma chave de conta BIP84 (xpub/zpub), que gera endereços SegWit nativos (p2wpkh).
• EVM / TRON: a chave no nível da conta (m/44'/60'/0' ou m/44'/195'/0'), que gera um endereço por intenção.

Uma carteira ativa por loja, rede e ambiente mantém o roteamento determinístico. A chave estendida é criptografada em repouso e nunca é retornada pela API — as respostas mostram apenas a impressão digital (fingerprint) e o modelo de derivação.

Gap limit

Os softwares de carteira param de buscar depois de uma sequência de endereços não usados (o gap limit, padrão 20 aqui). Cada intenção de pagamento reserva o próximo índice, então muitos checkouts abandonados podem ultrapassar o gap limit da sua carteira. O objeto da carteira expõe next_index, gap_limit e last_used_index; quando a sequência de endereços não usados se aproxima do limite, você é alertado para poder aumentar o gap limit no seu software de carteira. Os endereços nunca são reutilizados entre intenções.

Provas de titularidade

Para mostrar que você controla uma chave cadastrada, assine um desafio com a chave no índice de derivação 0:

1. POST /v1/wallets/{id}/ownership-challenge retorna message, address, method (eip191 para EVM, bip137 para Bitcoin) e expires_at.
2. Assine a message na sua carteira.
3. POST /v1/wallets/{id}/ownership-proof com { "signature": "…" }.

Desativação

POST /v1/wallets/{id}/disable interrompe novas derivações. Os endereços já entregues aos clientes continuam sendo observados até a janela deles terminar, para que pagamentos atrasados ainda sejam observados e informados.