Endpoints

Rotas da API de Stablecoin

Você pode ver os detalhes completos na referência da API.

Todas as rotas ficam sob /api/v1/stablecoin/ e exigem autenticação com o seu App (header Authorization). Cada rota exige um escopo (scope) específico no seu App:

Escopo	Rotas
STABLECOIN_DEPOSIT_CREATE	quote, deposit, deposit/approve
STABLECOIN_DEPOSIT_LIST	deposit/find, deposit (listar)
STABLECOIN_SUBACCOUNT_CREATE	subaccount (POST — solicitar KYB)
STABLECOIN_SUBACCOUNT_LIST	subaccount (listar), subaccount/{subAccountId}

A URL base de produção é https://api.woovi.com. Caso o App não tenha o escopo necessário, a resposta é 401 com Application is missing required scope: ....

Cotação (Quote)

GET /api/v1/stablecoin/quote

Retorna uma cotação BRL → stablecoin sem criar um depósito. Use para exibir ao cliente exatamente quanto de stablecoin ele receberia antes de confirmar. A cotação é armazenada em cache por 60 segundos.

Query params:

• value (obrigatório) — valor a cotar, em centavos de BRL (ex.: 10000 = R$ 100,00)
• currency (opcional) — USDT | USDC (padrão: USDT)

curl --request GET \
  --url 'https://api.woovi.com/api/v1/stablecoin/quote?value=10000&currency=USDT' \
  --header 'Authorization: <SEU_APP_ID>'

Resposta:

{
  "status": "ok",
  "quote": {
    "basePrice": 5.25,
    "inputAmount": 100,
    "inputCurrency": "BRL",
    "outputAmount": 19.04,
    "outputCurrency": "USDT",
    "appliedFees": [
      { "type": "In Fee", "amount": 1.5, "currency": "BRL" }
    ],
    "pairName": "BRL/USDT"
  }
}

inputAmount e outputAmount no retorno da cotação são em unidade de moeda (não em centavos). Caso o provedor não consiga cotar, a resposta é 502 com { "status": "error", "error": "Unable to fetch quote" }.

Criar um depósito

POST /api/v1/stablecoin/deposit

Cria um depósito de stablecoin a partir do saldo em BRL da conta. Retorna depositId, correlationId e uma cotação com as taxas aplicadas. A aprovação (/deposit/approve) é que debita o saldo da conta.

Body:

campo	tipo	obrigatório	descrição
value	number	sim	valor em centavos de BRL (ex.: 10000 = R$ 100,00)
currency	string	sim	USDT | USDC
network	string	não	POLYGON (padrão) | ETHEREUM | BASE | CELO | TRON
subAccountId	string	não	subconta a usar; resolvida pela empresa quando omitida
correlationId	string	não	identificador único para idempotência
destinationWalletAddress	string	não	carteira de destino explícita para a stablecoin

curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/deposit \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{
    "value": 10000,
    "currency": "USDT",
    "network": "POLYGON",
    "correlationId": "my-unique-id"
  }'

Resposta:

{
  "status": "PENDING",
  "depositId": "6650abc1234def567890aaaa",
  "correlationId": "my-unique-id",
  "expiration": "2026-06-05T12:00:00.000Z",
  "quote": {
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputAmount": 18.45,
    "outputCurrency": "USDT",
    "rate": 5.42,
    "fee": 50
  }
}

Erros comuns (400):

{ "error": "value must be a positive number (in cents)" }
{ "error": "currency must be one of: USDT, USDC" }
{ "error": "USDT is not available on BASE. Supported networks: POLYGON, ETHEREUM, CELO, TRON" }
{ "error": "Nenhuma subconta de stablecoin ativa. É necessário um KYB, entre em contato com o suporte." }

Aprovar (liquidar) um depósito

POST /api/v1/stablecoin/deposit/approve

Aprova um depósito já criado, identificado pelo correlationId, disparando a liquidação on-chain (pagamento do QR Code stablecoin). O depósito passa para PROCESSING enquanto a liquidação está em andamento.

Body:

• correlationId (obrigatório) — o correlationId informado na criação do depósito

curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/deposit/approve \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{ "correlationId": "my-unique-id" }'

Resposta:

{
  "status": "PROCESSING",
  "correlationId": "my-unique-id",
  "depositId": "6650abc1234def567890aaaa"
}

A aprovação é rejeitada com 400 quando o depósito não pode ser aprovado, por exemplo: já está COMPLETED, já está PROCESSING, não há conta de origem para pagar, ou a cotação/pagamento do provedor falhou.

{ "error": "Stablecoin deposit already completed", "correlationId": "my-unique-id", "depositId": "6650abc1234def567890aaaa" }

Buscar um depósito

GET /api/v1/stablecoin/deposit/find?correlationId={correlationId}

Busca um único depósito pelo correlationId.

{
  "status": "ok",
  "deposit": {
    "id": "6650abc1234def567890aaaa",
    "correlationId": "my-unique-id",
    "status": "COMPLETED",
    "inputAmount": 10000,
    "inputCurrency": "BRL",
    "outputAmount": 18.45,
    "outputCurrency": "USDT",
    "fee": 50,
    "createdAt": "2026-06-05T12:00:00.000Z"
  }
}

Listar depósitos

GET /api/v1/stablecoin/deposit?limit={limit}&skip={skip}

Lista os depósitos da empresa autenticada (paginado).

{
  "status": "ok",
  "deposits": [ { "id": "6650abc1234def567890aaaa", "status": "COMPLETED", "inputAmount": 10000, "inputCurrency": "BRL", "outputAmount": 18.45, "outputCurrency": "USDT", "fee": 50, "createdAt": "2026-06-05T12:00:00.000Z" } ],
  "count": 42,
  "limit": 20,
  "skip": 0
}

Solicitar uma subconta (KYB)

POST /api/v1/stablecoin/subaccount

Solicita a criação de uma subconta de stablecoin para a empresa autenticada, reaproveitando os dados de KYC já presentes no accountRegister informado. A subconta no provedor é criada imediatamente e um registro StableSubAccount é persistido com status IN_REVIEW enquanto o KYB é processado.

O processamento do KYB é assíncrono: quando ele é resolvido, a empresa recebe um webhook STABLECOIN_SUBACCOUNT_CONFIRMED ou STABLECOIN_SUBACCOUNT_REJECTED (veja Webhooks). Somente após o STABLECOIN_SUBACCOUNT_CONFIRMED a subconta pode ser usada em POST /api/v1/stablecoin/deposit.

A rota é idempotente por accountRegisterId: uma chamada repetida retorna a subconta já existente (HTTP 200), enquanto a primeira chamada (que cria) retorna HTTP 201. Exige o escopo STABLECOIN_SUBACCOUNT_CREATE.

Body:

campo	tipo	obrigatório	descrição
accountRegisterId	string	sim	id do accountRegister cujos dados de KYC serão usados no KYB
companyBankAccountId	string	não	conta bancária da empresa a vincular; usa a conta padrão da empresa quando omitida

curl --request POST \
  --url https://api.woovi.com/api/v1/stablecoin/subaccount \
  --header 'Authorization: <SEU_APP_ID>' \
  --header 'content-type: application/json' \
  --data '{
    "accountRegisterId": "6650abc1234def567890aaaa"
  }'

Resposta (201 na criação, 200 quando a subconta já existia):

{
  "subAccountId": "sub_01HZ...",
  "status": "IN_REVIEW",
  "correlationId": "0f2c8d6a-1b3e-4f5a-9c7d-8e2a1b4c6d8f"
}

Erros comuns:

{ "error": "accountRegisterId is required" }
{ "error": "INVALID_ACCOUNT_REGISTER_ID", "correlationId": "..." }
{ "error": "ACCOUNT_REGISTER_NOT_FOUND", "correlationId": "..." }
{ "error": "ACCOUNT_REGISTER_MISSING_OFFICIAL_NAME", "correlationId": "..." }

Erros que o chamador pode corrigir (id inválido, accountRegister inexistente ou sem dados obrigatórios) retornam 400. Falhas no provedor ou na persistência retornam 502 (ex.: AVENIA_SUBACCOUNT_CREATE_FAILED), indicando que a chamada pode ser repetida.

Listar subcontas

GET /api/v1/stablecoin/subaccount

Lista as subcontas de stablecoin (registros de KYB) da empresa autenticada.

{
  "status": "ok",
  "subAccounts": [
    {
      "id": "6650abc1234def567890aaaa",
      "subAccountId": "sub_01HZ...",
      "account": "6650def1234abc567890bbbb",
      "createdAt": "2026-06-05T12:00:00.000Z"
    }
  ]
}

Buscar uma subconta

GET /api/v1/stablecoin/subaccount/{subAccountId}

{
  "status": "ok",
  "subAccount": {
    "id": "6650abc1234def567890aaaa",
    "subAccountId": "sub_01HZ...",
    "account": "6650def1234abc567890bbbb",
    "createdAt": "2026-06-05T12:00:00.000Z"
  }
}