Vexus Docs

Vexus Crypto API v1

Integre ativos digitais
com contratos claros.

Autenticação HMAC, operações idempotentes, webhooks assinados e valores financeiros em unidades inteiras.

Começar integraçãoBaixar OpenAPI

Quick Start

Sua primeira chamada segura

Todas as rotas financeiras exigem os quatro headers de autenticação. O secret HMAC deve permanecer exclusivamente no seu servidor.

1. Crie uma API Key

No dashboard, escolha apenas os escopos necessários. O secret aparece uma única vez.

2. Canonicalize o request

Método, path exato, timestamp, nonce, idempotency key e SHA-256 do body, separados por nova linha.

3. Assine com HMAC-SHA256

Use o secret no servidor e envie o resultado hexadecimal em X-Vexus-Signature.

4. Use idempotência

Em wallets, saques, swaps e transferências, reutilize a mesma chave ao consultar uma tentativa incerta.

Headers obrigatórios

X-Vexus-Key: vx_example_xxxxxxxxx
X-Vexus-Timestamp: 1788314400
X-Vexus-Nonce: nonce_1234567890abcdef
X-Vexus-Signature: 330c61da...a09ba6e5
Idempotency-Key: wallet-example-001

Autenticação

Canonical Request, sem ambiguidades

O path inclui o prefixo /v1 e não inclui query string. O body é exatamente o JSON enviado; GET usa body vazio.

String canônica

POST
/v1/wallets
1788314400
nonce_1234567890abcdef
wallet-example-001
3a41ad33dd7cf270f45c1485968286de89eec3099881de1255498938dd4448b7

Vetor público de teste

Secret
your_hmac_secret
Body SHA-256
3a41ad33…448b7
HMAC esperado
330c61daf58ea440b86d10ddd750830122b710e3a4dc5b8c80dbf8a1a09ba6e5

cURL

curl https://api.vexuspay.fun/v1/wallets \
  -X POST -H 'Content-Type: application/json' \
  -H 'X-Vexus-Key: vx_example_xxxxxxxxx' \
  -H 'X-Vexus-Timestamp: 1788314400' \
  -H 'X-Vexus-Nonce: nonce_1234567890abcdef' \
  -H 'X-Vexus-Signature: 330c61da...a09ba6e5' \
  -H 'Idempotency-Key: wallet-example-001' \
  --data '{"external_user_id":"customer_123","network":"BSC"}'

Node.js

import crypto from "node:crypto";

const body = JSON.stringify({ external_user_id: "customer_123", network: "BSC" });
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const canonical = [method, path, timestamp, nonce, idempotencyKey, bodyHash].join("\n");
const signature = crypto.createHmac("sha256", "your_hmac_secret").update(canonical).digest("hex");

PHP

$bodyHash = hash('sha256', $body);
$canonical = implode("\n", [$method, $path, $timestamp, $nonce, $idempotencyKey, $bodyHash]);
$signature = hash_hmac('sha256', $canonical, 'your_hmac_secret');

Python

body_hash = hashlib.sha256(body.encode()).hexdigest()
canonical = "\n".join([method, path, timestamp, nonce, idempotency_key, body_hash])
signature = hmac.new(b"your_hmac_secret", canonical.encode(), hashlib.sha256).hexdigest()

Operação

Ambiente, limites e erros

Produção usa exclusivamente api.vexuspay.fun/v1. Cada credencial possui rate limit próprio; respostas 429 informam excesso de requisições e nunca devem ser contornadas com paralelismo agressivo.

Timestamp

Unix em segundos, com janela máxima de 300 segundos.

Nonce

Valor único de 16–128 caracteres. Reutilização retorna REPLAY_DETECTED.

Idempotência

Obrigatória nas mutações indicadas. Payload diferente retorna IDEMPOTENCY_CONFLICT.

Paginação

Listagens aceitam filtros e limit quando documentado; o limite máximo é 100.

Erros

Formato estável: code, message amigável e trace_id. Stack, SQL e provider nunca são expostos.

Cross-chain

USDT TRC20 e USDT BEP20 são redes distintas; CROSS_CHAIN_NOT_SUPPORTED permanece explícito.

Mapa da API

Catalog: networks, assets, swap-pairs
Wallets: create, details, balances, transactions
Deposits: list and details
Withdrawals: quote, execute and status
Swaps: quote, execute and actual settlement
Internal transfers and restricted admin resources

Conceitos

Comportamento financeiro previsível

A API diferencia prova on-chain, saldo disponível no ledger e estados transitórios.

Confirmações e reorg

Depósitos passam por detected, confirming, confirmed e credited. Reorgs nunca apagam o histórico.

Fees e gas

Quotes separam custo de rede, markup, taxa Vexus, spread e total debitado.

Precisão

Campos *_units são strings inteiras. Converta usando decimals do ativo e nunca use float.

Webhooks

Eventos verificáveis e resilientes

Cada entrega possui ID único, timestamp e assinatura. Responda 2xx rapidamente e processe de forma idempotente.

Assinatura de webhook

Canonical: timestamp.event_id.raw_body. A assinatura chega como X-Vexus-Signature: sha256=<hex>.

Retry e dead-letter

Falhas transitórias usam backoff exponencial com jitter. Rejeições permanentes e a décima falha seguem para dead-letter.

Webhook · Node.js

const expected = crypto.createHmac("sha256", webhookSecret)
  .update(timestamp + "." + eventId + "." + rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) throw new Error("invalid");

Webhook · PHP

$expected = hash_hmac('sha256', "$timestamp.$eventId.$rawBody", $webhookSecret);
if (!hash_equals('sha256='.$expected, $received)) { http_response_code(401); exit; }

Webhook · Python

expected = hmac.new(secret, f"{timestamp}.{event_id}.{raw_body}".encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest("sha256=" + expected, received): raise ValueError("invalid")

OpenAPI 3.1

Referência completa e interativa

Informe sua própria credencial apenas se decidir testar. Nenhuma master key é pré-carregada.