Transacoes

Conceitos rápidos

Uma transação é criada pela API e depois processada assíncronamente pelas etapas de preparação, assinatura, broadcast e confirmação.

Tipos de operação suportados

• transfer Transferência simples.
• contract_call Chamada de contrato.
• typed_message Assinatura de mensagem tipada EIP-712.

Observações específicas de Tron

• O fluxo Tron agora monta uma transação real antes da assinatura.
• Para transferência nativa de TRX, use operationType = transfer com calldata = 0x.
• Para smart contract em Tron, a API hoje consegue montar chamadas quando o seletor do calldata corresponde a assinaturas ABI conhecidas, como transfer(address,uint256), approve(address,uint256) e transferFrom(address,address,uint256).
• Chamadas arbitrárias de contrato Tron com seletor desconhecido ainda não são auto-montadas pela API.
• Para TRC20, o fluxo recomendado é usar operationType = contract_call, enviar o contrato no destination.address e o ABI-encoded no calldata.

Criar uma nova transação de saída.

Endpoint: POST /transactions Autenticação

Exige bearer token com permissão transaction:create.

Body base

{
  "source": {
    "vaultId": "12"
  },
  "destination": {
    "address": "0xA35Db58D2055e2aC965dA6Ff905bf12B62792Fe1"
  },
  "network": "polygon",
  "operationType": "transfer",
  "amount": "1000000000000000",
  "calldata": "0x"
}

Campos

• source.vaultId Vault funcional de origem.
• destination.address Destino da operação.
• network Nome da rede, como polygon, ethereum, tron.
• operationType transfer, contract_call ou typed_message.
• amount Opcional para alguns fluxos, sempre como string inteira.
• tokenAddress Opcional. Pode ser inferido em algumas chamadas EVM.
• typedData Obrigatório quando operationType = typed_message.
• calldata Obrigatório e precisa ser hex com prefixo 0x.
• masterKeyId Opcional.

Validações importantes

• typed_message só funciona em redes EVM.
• Para EVM, destination.address deve ser endereço hexadecimal válido.
• Para EVM, tokenAddress também deve ser endereço válido se enviado.
• calldata deve ser hex.
• amount deve ser string inteira positiva quando enviado.

Retorno

O retorno é a transação criada já enriquecida com metadados amigáveis.

Exemplo resumido:

{
  "id": "uuid",
  "vaultId": "12",
  "feePayerType": "relayer",
  "feePayerVaultId": "uuid-ou-null",
  "network": "polygon",
  "networkGroup": "evm",
  "operationType": "transfer",
  "tokenAddress": null,
  "amount": "1000000000000000",
  "destination": "0xa35d...",
  "calldata": "0x",
  "status": "Created",
  "createdBy": "uuid-do-api-user",
  "assetSymbol": "POL",
  "assetDecimals": 18,
  "intent": {
    "classification": "native_transfer",
    "methodSelector": null,
    "methodName": null,
    "tokenAddress": null,
    "from": null,
    "to": "0xa35d...",
    "amount": "1000000000000000"
  },
  "createdAt": "2026-03-26T12:00:00.000Z",
  "updatedAt": "2026-03-26T12:00:00.000Z"
}

Listar transações com páginação e filtros.

Endpoint: GET /transactions Autenticação

Exige bearer token com permissão transaction:read.

Query params

• page Padrão: 1.
• pageSize Padrão: 10. Máximo: 100.
• search Busca por id, destino, vaultId ou txHash.
• status Filtra por status.
• network Filtra por rede.

Retorno

{
  "items": [
    {
      "id": "uuid",
      "vaultId": "12",
      "feePayerType": "vault",
      "feePayerVaultId": null,
      "network": "polygon",
      "networkGroup": "evm",
      "operationType": "transfer",
      "tokenAddress": null,
      "amount": "1000",
      "destination": "0x...",
      "calldata": "0x",
      "rawTransactionHex": null,
      "signature": null,
      "txHash": null,
      "status": "Created",
      "failureReason": null,
      "createdBy": "uuid",
      "assetSymbol": "POL",
      "assetDecimals": 18,
      "intent": {
        "classification": "native_transfer",
        "methodSelector": null,
        "methodName": null,
        "tokenAddress": null,
        "from": null,
        "to": "0x...",
        "amount": "1000"
      },
      "createdAt": "2026-03-26T12:00:00.000Z",
      "updatedAt": "2026-03-26T12:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1
}

Consultar uma transação específica com histórico de status.

Endpoint: GET /transactions/:transactionId Autenticação

Exige bearer token com permissão transaction:read.

Parâmetros de rota

• transactionId UUID interno da transação.

Retorno

Mesmo formato do item de transação, com campos extras:

• history Histórico de status.
• simulation Resultado da simulação, quando aplicável.

Exemplo resumido:

{
  "id": "uuid",
  "status": "Confirming",
  "txHash": "0x...",
  "assetSymbol": "USDT",
  "assetDecimals": 6,
  "intent": {
    "classification": "erc20_transfer",
    "methodSelector": "0xa9059cbb",
    "methodName": "transfer(address,uint256)",
    "tokenAddress": "0x...",
    "from": null,
    "to": "0x...",
    "amount": "10000"
  },
  "simulation": {
    "attempted": true,
    "success": true,
    "result": "0x"
  },
  "history": [
    {
      "id": "uuid",
      "transactionId": "uuid",
      "status": "Created",
      "message": "transaction accepted",
      "metadataJson": null,
      "createdAt": "2026-03-26T12:00:00.000Z"
    }
  ]
}

Status comuns de transação

• Created
• AwaitingSignature
• Broadcasting
• Confirming
• Success
• Failed