API UnblockGlobal

Integre a compra de cripto (on-ramp via Pix): cotação, geração de pedido (Pix) e consulta de status — como um proxy da nossa infraestrutura, com as taxas da sua conta.

Introdução

A integração usa um handshake de cotação em três passos:

1. Cotação — envie o valor, a cripto/rede e a carteira de destino. Recebe um quote_id com o preço travado, válido por ~5 minutos (POST /quotes).
2. Criar pedido — passe apenas o quote_id. Gera o Pix com o preço cotado (POST /orders).
3. Status — acompanhe o pagamento e o envio on-chain (GET /orders/{uuid}).

Para usar a API você precisa de uma conta habilitada e de uma credencial (gerada no painel, em Desenvolvedores → Chave de API). As taxas aplicadas são exatamente as configuradas na sua conta.

⚡ Inicialmente apenas o fluxo de compra está disponível. Venda e outras moedas/países entram em breve.

Autenticação

Toda chamada autenticada usa sua secret key no cabeçalho Authorization:

Header

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

A public key (pk_live_…) é um identificador; a secret key (sk_live_…) é o que autentica — trate como senha.
Nunca exponha a secret key no front-end ou em repositórios públicos.
Em caso de vazamento, revogue e gere outra no painel — a antiga para de funcionar na hora.

Base URL

Base

https://api.unblockglobal.com/api/v1

Todas as respostas são JSON. Em validações, o corpo traz errors por campo (HTTP 422).

POST/quotes

Cotação (trava o preço)

Valida a carteira, calcula a compra e devolve um quote_id com o preço travado por ~5 minutos. Informe amount_brl (quanto pagar) ou crypto_receive (quanto receber).

Parâmetros (body)

Campo	Tipo	Descrição
`amount_brl`	number	Valor em BRL a pagar (mín. 150). um dos dois
`crypto_receive`	number	Alternativa: quantidade de cripto a receber. um dos dois
`asset`	string	`USDT` ou `USDC`. obrigatório
`network`	string	`ethereum`, `polygon`, `solana`, `tron`. obrigatório
`wallet_address`	string	Carteira que vai receber a cripto. obrigatório

cURL

curl -X POST https://api.unblockglobal.com/api/v1/quotes \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_brl":200,"asset":"USDT","network":"polygon","wallet_address":"0xABC..."}'

200 OK

{
  "quote_id": "qt_xxxxxxxxxxxxxxxxxxxx",
  "asset": "USDT",
  "network": "polygon",
  "wallet_address": "0xABC...",
  "amount_brl": 200,
  "crypto_amount": 36.11,
  "quotation": 5.2102,
  "fee": {
    "percent": 3,
    "variable": 1.05,
    "fixed": 1,
    "network": 2,
    "total": 4.05,
    "currency": "USDT"
  },
  "expires_at": "2026-06-09T20:05:00Z"
}

Campos da resposta

Campo	Descrição
`quote_id`	Use no POST /orders para criar o pedido com este preço.
`crypto_amount`	Quanto de cripto o cliente recebe.
`quotation`	Cotação aplicada (BRL por unidade da cripto).
`expires_at`	Validade da cotação (~5 min). Depois disso, gere uma nova.

Objeto `fee`

Campo	Descrição
`percent`	Percentual total cobrado sobre o valor.
`variable`	Quanto o percentual representa, na moeda (`currency`).
`fixed`	Taxa fixa por operação.
`network`	Taxa de rede (envio on-chain).
`total`	Total de taxas (`variable + fixed + network`).
`currency`	Moeda das taxas (ex.: `USDT`).

POST/orders

Criar pedido (gera o Pix)

Cria o pedido a partir de um quote_id travado — o preço já foi definido na cotação. Retorna o Pix copia-e-cola e os dados do pedido.

Parâmetros (body)

Campo	Tipo	Descrição
`quote_id`	string	O `quote_id` retornado em POST /quotes (válido ~5 min). obrigatório
`external_id`	string	Seu identificador para o pedido (ex.: nº do pedido na sua loja). Permite consultar depois pelo seu próprio ID. opcional

cURL

curl -X POST https://api.unblockglobal.com/api/v1/orders \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"qt_xxxxxxxxxxxxxxxxxxxx","external_id":"pedido-loja-123"}'

201 Created

{
  "data": {
    "uuid": "9b1c8f2e-...",
    "external_id": "pedido-loja-123",
    "status": "pending",
    "display_status": "awaiting_payment",
    "asset": "USDT",
    "network": "polygon",
    "wallet_address": "0xABC...",
    "amount_brl": 200,
    "crypto_amount": 36.11,
    "quotation": 5.2102,
    "fee": { "percent": 3, "variable": 1.05, "fixed": 1, "network": 2, "total": 4.05, "currency": "USDT" },
    "pix_copy_paste": "00020101...6304ABCD",
    "expires_at": "2026-06-09T20:10:00Z"
  }
}

📲 O pix_copy_paste é a string do Pix — gere o QR Code com qualquer lib sobre ela. O prazo de pagamento vem em expires_at; depois disso o pedido expira (se pago após o prazo, a cotação usada é a do momento da transação).

GET/orders/{uuid}

Status do pedido

Consulta o estado do pedido (sincronizado com a liquidação). Você pode usar o uuid retornado na criação ou o seu external_id.

cURL — por uuid ou external_id

curl https://api.unblockglobal.com/api/v1/orders/9b1c8f2e-... \
  -H "Authorization: Bearer sk_live_xxx"

curl https://api.unblockglobal.com/api/v1/orders/pedido-loja-123 \
  -H "Authorization: Bearer sk_live_xxx"

200 OK

{ "data": { "uuid": "9b1c8f2e-...", "external_id": "pedido-loja-123",
  "status": "paid", "display_status": "completed", "tx_hash": "0x...",
  "fee": { "percent": 3, "total": 4.05, "currency": "USDT" } } }

Estados (display_status)

Valor	Significado
`awaiting_payment`	Aguardando o pagamento do Pix.
`processing`	Pago; enviando a cripto.
`completed`	Cripto enviada — ver `tx_hash`.
`expired` / `failed`	Prazo vencido sem pagamento / falhou.

💡 Para acompanhar em tempo real, faça polling a cada poucos segundos enquanto estiver awaiting_payment/processing.

POST/wallets/validate

Validar carteira

Valida um endereço numa rede antes de criar o pedido (evita erros de digitação e endereços bloqueados).

cURL

curl -X POST https://api.unblockglobal.com/api/v1/wallets/validate \
  -H "Authorization: Bearer sk_live_xxx" -H "Content-Type: application/json" \
  -d '{"address":"0xABC...","network":"polygon"}'

200 OK

{ "valid": true, "is_blocklisted": false }

Erros

HTTP	Quando
`401`	Secret key ausente, inválida ou revogada.
`403`	Conta sem acesso à API ou sem KYC aprovado.
`422`	Dados inválidos (resposta traz `errors` por campo).
`429`	Limite de requisições atingido.

Postman

Baixe a collection pronta (com auth e variáveis) e comece em minutos:

Baixar collection do Postman

Documentação da API

API UnblockGlobal

Introdução

Autenticação

Base URL

Cotação (trava o preço)

Parâmetros (body)

Campos da resposta

Objeto fee

Criar pedido (gera o Pix)

Parâmetros (body)

Status do pedido

Estados (display_status)

Validar carteira

Erros

Postman

Objeto `fee`