Pular para o conteúdo

Saques automáticos

Os saques automáticos tiram dinheiro da sua carteira Invoise sem uma confirmação para cada saque. Para cada rede você define um limite; quando a carteira tem esse valor lá, todo o saldo dessa rede vai para um endereço externo seu. Seu próprio servidor de assinatura assina as transações e o Invoise adiciona a segunda assinatura.

Você os configura no painel: Carteira → Segurança → Automação de saques → Configurar. Cada regra em Regras por rede define:

  • Da rede: a rede cujo saldo é sacado. Uma regra por rede.
  • Para a rede: para onde vai o dinheiro. Pode ser a mesma rede; nesse caso nenhuma ponte é usada.
  • Token: um dos tokens que o Invoise suporta na rede de destino.
  • Limite em dólares: a partir do saque mínimo, com no máximo duas casas decimais.

Os pagamentos em Tron e Solana chegam à carteira no Arbitrum (veja Solana e Tron), então contam na regra do Arbitrum. Não há regra separada para Tron ou Solana.

Quando a carteira tem pelo menos o limite em uma rede de origem, o Invoise saca todo o saldo dessa rede, em quaisquer stablecoins, menos a taxa, para o Endereço do destinatário. O saldo da própria rede de destino fica onde está. Uma stablecoin que nenhuma ponte consegue levar ao token de repasse, como USDT0 no Arbitrum para USDC na Base, é primeiro trocada pelo USDC dessa rede na Uniswap, e o CCTP da Circle então move o USDC. Uma stablecoin da família do token de repasse viaja pelo Across, e uma regra cujo destino é a própria origem faz a troca nessa rede, como um saque manual. A taxa é a mesma de um saque manual.

O Invoise verifica as regras a cada minuto e envia um saque automático por vez: o da primeira regra cuja rede atingiu o limite.

Configuração Significado
No máximo Sem limite, ou uma vez por hora, a cada 3, 6 ou 12 horas, uma vez por dia ou uma vez por semana.
Desativar após falhas seguidas De 1 a 10, 3 por padrão. Após uma falha, a próxima tentativa espera 5 minutos, depois 30 minutos, depois 2 horas. Você é avisado da primeira falha de uma sequência e quando os saques automáticos são desativados.
Taxa de no máximo 0,5%, 1%, 2%, 3%, 5% ou 10% do valor que chega ao destinatário, 1% por padrão.

O teto de taxa cobre o gas de rede de todas as etapas. Quando o gas custa mais, o saque dessa rede espera: o painel mostra Aguardando taxa menor com a taxa e o valor, e o saque sai quando o saldo cresce ou o gas fica mais barato. Uma espera não é uma falha. As taxas de ponte e de troca crescem com o valor e são limitadas pela rota: uma troca que perderia mais de 3% é recusada.

O limite diário e a pausa da carteira também valem para os saques automáticos. Desativá-los e restringir as regras vale imediatamente. Com a espera ativada, ativá-los, outro servidor de assinatura ou destinatário, uma regra nova ou redirecionada, um limite ou intervalo menor, mais falhas toleradas e um teto de taxa maior só valem após a espera; o painel mostra quando, e até lá a alteração pode ser cancelada. Cada alteração envia um aviso de segurança e, se a conta tiver 2FA, pede um segundo fator.

A carteira é um Safe com limiar de 2 de 3, então cada saque precisa de duas assinaturas. O cossignatário Invoise fornece uma delas. Em um saque manual, a outra vem da sua chave do lojista, que nunca sai do seu navegador, então ela não pode assinar enquanto você está ausente.

O Invoise nunca guarda duas chaves da sua carteira. Nos saques automáticos, a segunda assinatura vem do seu próprio servidor de assinatura, que guarda uma das chaves da carteira que você controla: a chave do delegado ou sua chave do lojista. O Invoise aceita qualquer uma das duas sem perguntar qual é; a escolha decide o que uma chave do servidor vazada pode fazer:

  • Chave do delegado. O cossignatário Invoise aceita a assinatura do delegado sozinha apenas enquanto os saques automáticos estão ativados e apenas para repasses ao endereço do destinatário que você definiu; todo o resto continua exigindo sua chave do lojista. Por isso uma chave do servidor vazada não consegue enviar dinheiro para outro lugar pelo Invoise.
  • Chave do lojista. Não há mais nada a configurar, mas o cossignatário aceita a chave do lojista para tudo o que você mesmo pode fazer. Com uma chave do servidor vazada é possível sacar para qualquer endereço, alterar as proteções e substituir chaves pelo Invoise; só continuam valendo o limite diário, a pausa e a espera. A chave passa a ficar no servidor além do seu navegador.

Um servidor com a chave do delegado também tem todos os poderes de um delegado: sozinha ela pode enfileirar um saque pelo módulo de atraso, que é executado após três dias, a menos que você o cancele (veja Se o Invoise estiver indisponível). Guarde a chave do servidor com o mesmo cuidado que a chave da carteira.

  1. Execute em uma URL HTTPS pública um servidor de assinatura que siga o protocolo. Endereços locais e privados são recusados.
  2. Abra Carteira → Segurança → Automação de saques → Configurar e clique em Emitir segredo em Servidor de assinatura. O segredo é mostrado uma única vez: salve-o no seu servidor. Emitir um novo o substitui, e requisições assinadas com o antigo deixam de ser verificadas na hora.
  3. Informe a URL do servidor de assinatura, o Endereço do destinatário, as regras e os limites, ative a chave Saques automáticos ativados e clique em Salvar. O Invoise pede ao servidor que se identifique e mostra a chave dele como Chave do servidor.
  4. Se a chave do servidor for sua chave do lojista, o status vira Ativo na hora e a configuração termina. Caso contrário, a seção diz O servidor de assinatura não é o delegado. Clique em Tornar delegado. Enquanto a carteira não estiver implantada em nenhuma rede, o servidor vira delegado na hora; caso contrário, confirme a transação com sua chave do lojista em cada rede implantada. Um delegado atual é substituído. Trocar o delegado é uma alteração de segurança, então, com a espera ativada, ela pausa os saques.
  5. Quando o servidor é o delegado, o Invoise permite que seu cossignatário aceite a assinatura do servidor para o seu endereço de destinatário, e o status passa a Ativo.
Status Significado
Desativado Os saques automáticos estão desligados.
Aguardando delegado A chave do servidor não é sua chave do lojista nem o delegado da carteira: clique em Tornar delegado.
Nova tentativa após erro A última tentativa falhou; o painel mostra o erro e as falhas seguidas.
Ativo Os saques rodam conforme as regras.

Um novo servidor de assinatura salvo com a espera ativada aguarda o fim da espera, como qualquer afrouxamento. Se você o tornar delegado antes de a alteração valer, as configurações atuais apontam para um servidor que já não é o delegado, e nada é sacado até a alteração entrar em vigor.

O Invoise envia cada requisição como POST para a URL do seu servidor de assinatura com um corpo JSON, Content-Type: application/json, User-Agent: Invoise-Automation/1 e o cabeçalho Invoise-Signature: t=<unix time>,v1=<hex>. A assinatura é HMAC-SHA256 de t + "." + raw_body. A chave HMAC é a string inteira do segredo como aparece no painel, com o prefixo ias_ incluído (ias_ e 64 caracteres hexadecimais).

É o esquema dos webhooks, e a função verify de lá funciona sem alterações com esse segredo. O servidor DEVE recusar uma requisição cuja assinatura não seja verificada ou cujo t esteja a mais de 5 minutos do próprio relógio. A assinatura cobre apenas o horário e o corpo, então o servidor DEVE responder a um operation_id repetido com as assinaturas que já deu, ou com uma recusa, e nunca assinar dados diferentes sob o mesmo operation_id.

O servidor responde 200 com um corpo JSON; qualquer outro status é uma recusa. A resposta inteira deve chegar em até 30 segundos e ter no máximo 1 MiB. Redirecionamentos não são seguidos.

Enviado quando você salva uma nova URL de servidor de assinatura. O endereço recuperado da resposta vira a chave do servidor. Ela vale se for sua chave do lojista ou o delegado da carteira; qualquer outra chave você então torna delegado.

{
"type": "identify",
"wallet": "0x41d97e9d7b8d051f1ac4adaf92ca1e7b8c788375",
"message": "Invoise automatic withdrawals\nWallet: 0x41d97e9d7b8d051f1ac4adaf92ca1e7b8c788375\nServer: https://signer.example.com/invoise\nNonce: 5f0c4a7e9b2d81f3a6c0e47d1b9a2f68\nIssued At: 2026-10-04T12:00:00Z"
}

Responda com uma assinatura EIP-191 (personal_sign) de message, exatamente como recebida, feita com a chave do servidor (a do delegado ou sua chave do lojista), e o endereço dessa chave:

{ "address": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4", "signature": "0x…" }

O endereço deve ser aquele para o qual a assinatura é recuperada, e não pode ser o cossignatário Invoise.

Enviado uma vez para cada saque automático. Este move USDT0 e USDC do Arbitrum para USDC na Base:

{
"type": "sign",
"operation_id": "9b0f5c2e-4a1d-4f6b-8c3e-2d7a9e1f0b64",
"wallet": "0x41d97e9d7b8d051f1ac4adaf92ca1e7b8c788375",
"source_chain_id": 42161,
"chain_id": 8453,
"token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"symbol": "USDC",
"decimals": 6,
"amount": "249310000",
"payee": "0x2f1e7c3b9a4d5e6f708192a3b4c5d6e7f8091a2b",
"total_fee_usd": "0.11",
"legs": [
{
"position": 0,
"chain_id": 42161,
"safe": "0x41d97e9d7b8d051f1ac4adaf92ca1e7b8c788375",
"fee_recipient": "0x…",
"intent": "swap",
"safe_tx": { "to": "0x9641d764fc13c8b624c04430c7356c1c7c8102e2", "value": "0", "data": "0x8d80ff0a…", "operation": 1, "nonce": "4" },
"hash": "0x…",
"token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
"symbol": "USDC",
"decimals": 6,
"amount": "0",
"fee": { "token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "amount": "37000" },
"swap": { "router": "0x…", "spender": "0x…", "token_in": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", "amount_in": "120000000", "token_out": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "min_out": "119380000" },
"bridge": null,
"deploys": false
},
{
"position": 1,
"chain_id": 42161,
"safe": "0x41d97e9d7b8d051f1ac4adaf92ca1e7b8c788375",
"fee_recipient": "0x…",
"intent": "burn",
"safe_tx": { "to": "0x9641d764fc13c8b624c04430c7356c1c7c8102e2", "value": "0", "data": "0x8d80ff0a…", "operation": 1, "nonce": "5" },
"hash": "0x…",
"token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
"symbol": "USDC",
"decimals": 6,
"amount": "249400000",
"fee": { "token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "amount": "30000" },
"swap": null,
"bridge": null,
"deploys": false
},
{
"position": 3,
"chain_id": 8453,
"safe": "0x41d97e9d7b8d051f1ac4adaf92ca1e7b8c788375",
"fee_recipient": "0x…",
"intent": "withdraw",
"safe_tx": { "to": "0x9641d764fc13c8b624c04430c7356c1c7c8102e2", "value": "0", "data": "0x8d80ff0a…", "operation": 1, "nonce": "0" },
"hash": "0x…",
"token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"symbol": "USDC",
"decimals": 6,
"amount": "249310000",
"fee": { "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "20000" },
"swap": null,
"bridge": null,
"deploys": true
}
]
}
Campo Significado
operation_id Um saque automático.
source_chain_id, chain_id, token, amount, payee A rede de origem da regra e o que chega ao destinatário na rede de destino.
total_fee_usd A taxa de rede de todas as etapas, em USD.
legs As transações Safe a assinar. Um recebimento do CCTP ou um fill do Across não precisa de assinatura, então as posições podem pular números.
safe O endereço Safe da carteira na rede da etapa.
intent withdraw, swap, burn ou bridge.
safe_tx A transação Safe: to, value, data, operation, nonce.
fee, fee_recipient A taxa de rede da etapa e para onde ela é paga.
swap, bridge A troca ou o depósito no Across que a etapa faz; caso contrário, null.
deploys O Safe ainda não tem código nessa rede: ele é implantado na mesma transação, e o nonce é 0.

Valores, nonces e value são strings decimais em unidades do token; decimals e operation são números.

Responda com uma assinatura por etapa:

{ "signatures": [ { "position": 0, "signature": "0x…" }, { "position": 1, "signature": "0x…" }, { "position": 3, "signature": "0x…" } ] }

Cada assinatura é a assinatura ECDSA de 65 bytes da chave do servidor (r‖s‖v, v como 27/28 ou 0/1) sobre o hash SafeTx da etapa. Uma assinatura que não é recuperada nem para o delegado da carteira nem para sua chave do lojista faz o saque falhar com automation_signature_invalid.

A chave do servidor é uma das duas assinaturas de que o Safe precisa, então seu servidor é a verificação que impede o Invoise de agir sozinho. Antes de assinar uma etapa, ele DEVE:

  1. Calcular o hash por conta própria. Calcular o hash EIP-712 do Safe 1.4.1 e assinar apenas ele, nunca o campo hash como recebido. Domínio: EIP712Domain(uint256 chainId,address verifyingContract) com chain_id e safe da etapa. Mensagem: SafeTx(address to,uint256 value,bytes data,uint8 operation,uint256 safeTxGas,uint256 baseGas,uint256 gasPrice,address gasToken,address refundReceiver,uint256 nonce) com to, value, data, operation e nonce de safe_tx, safeTxGas, baseGas e gasPrice iguais a 0, e gasToken e refundReceiver iguais ao endereço zero. safe deve ser a carteira que ele atende nessa rede.

  2. Verificar o lote. operation 1 (DELEGATECALL) só é permitida para MultiSendCallOnly 0x9641d764fc13c8b624c04430c7356c1c7c8102e2 com a chamada multiSend(bytes), e cada item do lote deve ser uma chamada simples (operation 0) com valor 0. Uma chamada única vem com operation 0. Recusar qualquer outro DELEGATECALL e qualquer administração do Safe: swapOwner, addOwnerWithThreshold, removeOwner, changeThreshold, enableModule, disableModule, setGuard, setFallbackHandler, execTransactionFromModule, ou qualquer chamada ao próprio Safe.

  3. Verificar cada chamada. Exatamente um transfer(fee_recipient, fee.amount) de fee.token. Um approve apenas do valor exato que a próxima chamada gasta: para swap.spender de swap.token_in e swap.amount_in, para o TokenMessengerV2 do CCTP 0x28b5a0e9c621a5badaa536219b3a228c8168cf5d do valor queimado, ou para bridge.spoke_pool de bridge.token_in e bridge.amount_in. Depois, conforme o intent:

    • withdraw: um transfer do token de repasse para o endereço do destinatário que o servidor tem registrado;
    • swap: uma chamada a swap.router cujo resultado fica no Safe;
    • burn: depositForBurn no TokenMessengerV2 com mintRecipient igual ao Safe, preenchido até 32 bytes;
    • bridge: depositV3 em bridge.spoke_pool com o Safe como depositante e como destinatário.

    Recusar qualquer outra coisa.

  4. Aplicar os próprios limites. Comparar amount e total_fee_usd com os próprios limites, como por saque, por dia e percentual de taxa, e o destinatário com a própria configuração, nunca com o payee da requisição.

O cossignatário Invoise aplica as mesmas regras antes de assinar, então uma requisição correta sempre passa por elas. O servidor as repete porque não deve confiar no Invoise.

Seu servidor pode ler no Invoise aquilo com que compara as requisições, assinando com o mesmo segredo. Envie GET para https://platform.invoise.me/api/v1/automation/<recurso>?wallet=<endereço do Safe> com o cabeçalho Invoise-Signature: t=<hora unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de t + "." + caminho e query, por exemplo 1791200000./api/v1/automation/settings?wallet=0x41d9…. É a função de assinatura dos webhooks com o caminho da requisição no lugar do corpo. t pode diferir do relógio do Invoise em no máximo 5 minutos. Assinatura errada, t vencido, carteira desconhecida e carteira sem segredo recebem igualmente 401.

Caminho Resposta
/automation/settings O destinatário, as regras, os limites, o status e a alteração pendente; owners (merchant, delegate, cosigner), server_key_role (merchant, delegate ou vazio) e as proteções da carteira protections (limite diário, espera, pausa).
/automation/networks Por rede: safe, deployed, tokens, fee_recipient, multisend e, onde a rede os suporta, cctp (token_messenger, domain, usdc), swap (router, spender) e across (spoke_pool); caso contrário, null.
/automation/operations Saques automáticos, os mais recentes primeiro, com etapas, status e hashes de transação; limit de 1 a 100, 50 por padrão.
/automation/operations/{id} Um saque automático, por exemplo o operation_id de uma requisição sign.

Use as respostas para preencher e comparar a configuração própria do servidor, não como a verificação em si. Elas vêm do mesmo Invoise contra o qual seu servidor protege, então o destinatário, os limites e os contratos permitidos com que o servidor assina devem ser dele.

Esses códigos aparecem no painel, no aviso de falha e ao salvar as configurações.

Código Significado
automation_server_unreachable O servidor não respondeu em 30 segundos, ou sua URL não é mais um endereço HTTPS público.
automation_server_refused O servidor respondeu com um status diferente de 200; na maioria das vezes ele ainda tem um segredo antigo.
automation_server_invalid A resposta não era um JSON válido no formato esperado, a assinatura de identify não é recuperada para o endereço informado, ou a chave é o cossignatário.
automation_signature_invalid Uma assinatura não é recuperada nem para o delegado da carteira nem para sua chave do lojista: a chave do servidor mudou. Salve a URL de novo para que o servidor se identifique e depois torne-o delegado, se não for sua chave do lojista.
route_unavailable, swap_quote_failed Nenhuma rota de ponte ou de troca consegue mover esse saldo agora. Aumente o limite ou use uma regra dentro de uma mesma rede.