CKrypto OTC API — Referência

CKrypto OTC API

Documentação da API de On/Off-Ramp B2B — versão 1.0

Visão Geral

A CKrypto OTC API permite que empresas parceiras integrem operações de compra e venda de USDT (On-Ramp e Off-Ramp) diretamente nos seus sistemas, sem necessidade de acesso manual ao portal.

Com a API você pode:

Consultar cotações em tempo real com seu spread contratado
Criar ordens de compra (On-Ramp: BRL → USDT) ou venda (Off-Ramp: USDT → BRL)
Consultar o status e histórico das suas ordens
Receber notificações automáticas via Webhook quando suas ordens forem processadas

ℹ️ A API opera no padrão REST, retorna respostas em JSON e usa autenticação via API Key no header das requisições.

Autenticação

Todas as requisições devem incluir sua API Key no header X-API-Key.

Sua API Key é gerada pela CKrypto e fornecida após a ativação da conta. Em caso de comprometimento, solicite a regeneração via suporte.

Exemplo de header

# Todas as requisições devem incluir:
X-API-Key: sua_api_key_aqui
Content-Type: application/json
    

⚠️ Segurança: nunca exponha sua API Key em código frontend, repositórios públicos ou logs. Use variáveis de ambiente no servidor.

Fluxo de Operação

On-Ramp — Comprar USDT (BRL → USDT)

Consultar cotação

GET /quote?type=buy&amount=50000 — obtenha a taxa com seu spread

Criar ordem

POST /orders — informe o valor em BRL e carteira USDT destino

Enviar PIX

Transfira o valor BRL para a chave PIX da CKrypto informada na resposta

Confirmar pagamento

POST /orders/:id/paid — informe que o PIX foi enviado (com comprovante opcional)

Receber USDT

A CKrypto verifica e envia os USDT para sua carteira. Você recebe um webhook order.settled

Off-Ramp — Vender USDT (USDT → BRL)

Consultar cotação

GET /quote?type=sell&amount=50000

Criar ordem

POST /orders com type=sell — informe valor BRL e chave PIX para receber

Enviar USDT

Transfira os USDT-TRC20 para a carteira da CKrypto informada na resposta

Confirmar envio

POST /orders/:id/paid com o txid da transação blockchain

Receber BRL

A CKrypto confirma e envia o BRL via PIX. Você recebe um webhook order.settled

Ambientes

Ambiente	URL Base	Uso
Produção	`https://api.ckrypto.com.br/api/otc/v1`	Operações reais

ℹ️Para testes, entre em contato com o suporte para acesso a um ambiente de sandbox.

Endpoints

GET /quote Cotação indicativa

Retorna a cotação BRL/USDT com o spread contratado do seu parceiro.

Query Parameters

Parâmetro	Tipo	Descrição
type*	string	`buy` (BRL→USDT) ou `sell` (USDT→BRL)
amountopcional	number	Valor em BRL para calcular o USDT estimado

Requisição

GET /api/otc/v1/quote?type=buy&amount=50000
X-API-Key: sua_api_key

Resposta 200

{
  “order_type”:      “buy”,
  “reference_rate”: 5.7300,
  “spread”:          0.015,
  “net_rate”:        5.8160,      // taxa final com spread
  “fiat_amount”:     50000.00,
  “crypto_amount”:   8597.247,   // USDT estimado
  “fee_brl”:         750.00,     // taxa em BRL
  “currency_pair”:   “BRL/USDT”,
  “disclaimer”:      “Cotação indicativa. Confirmada pela CKrypto.”,
  “expires_at”:      “2026-05-11T14:30:00Z”
}

POST /orders Criar nova ordem

Cria uma nova ordem de On-Ramp ou Off-Ramp.

Body (JSON)

Campo	Tipo	Descrição
type*	string	`buy` ou `sell`
fiat_amount*	number	Valor da operação em BRL
usdt_wallet* buy	string	Carteira TRC20 para receber USDT (obrigatório em compras)
pix_key* sell	string	Chave PIX para receber BRL (obrigatório em vendas)
external_refopcional	string	ID do pedido no seu sistema (para reconciliação)
notesopcional	string	Observações internas

Exemplo — On-Ramp (compra de USDT)

POST /api/otc/v1/orders
X-API-Key: sua_api_key
Content-Type: application/json

{
  “type”:         “buy”,
  “fiat_amount”:  50000,
  “usdt_wallet”:  “TRxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx”,
  “external_ref”: “PED-2026-0042”
}

Resposta 201

{
  “order_id”:      “a1b2c3d4-…”,
  “status”:        “draft”,
  “order_type”:    “buy”,
  “fiat_amount”:   50000.00,
  “crypto_amount”: 8597.247000,
  “rate”:           5.8160,
  “fee_brl”:        750.00,
  “external_ref”:  “PED-2026-0042”,
  “payment_instruction”: {
    “action”:       “Envie BRL via PIX”,
    “pix_key”:      “pagamentos@ckrypto.com.br”,
    “pix_key_type”: “email”,
    “amount_brl”:   50000.00,
    “description”:  “OTC-A1B2C3D4”    // use como descrição do PIX
  },
  “created_at”:    “2026-05-11T14:00:00Z”,
  “expires_in_minutes”: 30
}

GET /orders Listar ordens

Lista todas as ordens do parceiro, com paginação e filtros.

Query Parameters

Parâmetro	Tipo	Padrão	Descrição
status	string	all	`draft` `confirmed` `paid` `settled` `cancelled`
page	integer	1	Número da página
per_page	integer	20	Registros por página (máx. 50)

Resposta 200

{
  “orders”: [ /* array de objetos Order */ ],
  “total”:   42,
  “page”:    1,
  “pages”:   3
}

GET /orders/{order_id} Detalhes de uma ordem

Retorna todos os detalhes de uma ordem específica, incluindo comprovantes e instruções de liquidação.

Resposta 200

{
  “order_id”:               “a1b2c3d4-…”,
  “order_type”:             “buy”,
  “status”:                 “settled”,
  “fiat_amount”:            50000.00,
  “crypto_amount”:          8597.247000,
  “rate”:                    5.8160,
  “fee_brl”:                 750.00,
  “usdt_wallet_destination”: “TRxxxx…”,
  “payment_proof”:           “E00123456…”,   // end-to-end ID do PIX
  “settlement_proof”:        “abc123txhash”,  // txid blockchain
  “nf_number”:               “NF-001234”,
  “external_ref”:            “PED-2026-0042”,
  “created_at”:              “2026-05-11T14:00:00Z”,
  “paid_at”:                 “2026-05-11T14:08:00Z”,
  “settled_at”:              “2026-05-11T14:35:00Z”
}

POST /orders/{order_id}/paid Confirmar pagamento realizado

Informa à CKrypto que você realizou o pagamento (PIX enviado para on-ramp, ou USDT enviado para off-ramp). A CKrypto verificará e processará a liquidação.

Body (JSON)

Campo	Tipo	Descrição
payment_proofopcional	string	End-to-end ID do PIX ou txid blockchain
notesopcional	string	Observação adicional

Exemplo

POST /api/otc/v1/orders/a1b2c3d4-…/paid

{
  “payment_proof”: “E00123456202605111408001234567890”,
  “notes”:          “PIX enviado às 14:08”
}

Resposta 200

{
  “order_id”: “a1b2c3d4-…”,
  “status”:   “paid”,
  “paid_at”:  “2026-05-11T14:08:00Z”,
  “message”:  “Pagamento registrado. A CKrypto irá verificar e processar a liquidação.”
}

Webhooks

Configure uma URL de webhook na CKrypto para receber notificações automáticas quando o status de suas ordens mudar. Ideal para automatizar a liberação de produtos/serviços no seu sistema.

Configuração

Informe sua URL de webhook ao time da CKrypto. A URL deve:

Ser HTTPS
Retornar HTTP 200 em até 10 segundos
Estar acessível pela internet (sem autenticação de IP)

Exemplo de payload recebido

{
  “event”:            “order.settled”,
  “order_id”:         “a1b2c3d4-…”,
  “status”:           “settled”,
  “order_type”:       “buy”,
  “fiat_amount”:      50000.00,
  “crypto_amount”:    8597.247,
  “rate”:              5.8160,
  “fee_brl”:           750.00,
  “external_ref”:     “PED-2026-0042”,
  “settlement_proof”: “abc123txhash”,
  “settled_at”:       “2026-05-11T14:35:00Z”,
  “timestamp”:        “2026-05-11T14:35:01Z”
}

Eventos disponíveis

Evento	Quando ocorre
`order.confirmed`	CKrypto confirmou a cotação da ordem
`order.paid`	Pagamento registrado no sistema
`order.settled`	Liquidação concluída — USDT ou BRL enviado
`order.cancelled`	Ordem cancelada
`order.disputed`	Ordem em disputa — aguarde contato

Verificação de Assinatura

Cada requisição de webhook inclui o header X-CKrypto-Signature com uma assinatura HMAC-SHA256 do corpo da requisição, usando seu Webhook Secret.

Verificação em Python

import hmac, hashlib

def verify_webhook(body_bytes, signature_header, secret):
    expected = “sha256=” + hmac.new(
        secret.encode(), body_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# No seu endpoint Flask/Django/FastAPI:
sig = request.headers.get(“X-CKrypto-Signature”)
if not verify_webhook(request.data, sig, WEBHOOK_SECRET):
    return “Unauthorized”, 401

Verificação em Node.js

const crypto = require(‘crypto’)

function verifyWebhook(body, signatureHeader, secret) {
  const expected = ‘sha256=’ + crypto
    .createHmac(‘sha256’, secret)
    .update(body)
    .digest(‘hex’)
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signatureHeader)
  )
}

Status das Ordens

Status	Descrição	Próximo passo
`draft`	Ordem criada — aguardando pagamento	Envie o pagamento e chame `/paid`
`confirmed`	CKrypto confirmou a cotação	Envie o pagamento e chame `/paid`
`paid`	Pagamento registrado — em processamento	Aguarde o webhook `order.settled`
`settled`	Liquidação concluída	—
`cancelled`	Ordem cancelada	Abra uma nova ordem se necessário
`disputed`	Em disputa — pendência identificada	Aguarde contato da CKrypto

Códigos de Erro

HTTP	code	Descrição
401	UNAUTHORIZED	API Key ausente, inválida ou conta inativa
400	INVALID_PARAM	Parâmetro inválido ou com formato incorreto
400	MISSING_FIELD	Campo obrigatório não informado
404	NOT_FOUND	Ordem não encontrada ou não pertence ao parceiro
422	BELOW_MINIMUM	Valor abaixo do mínimo contratado
422	ABOVE_MAXIMUM	Valor acima do limite por ordem
422	INVALID_STATUS_TRANSITION	Status não pode ser alterado para o solicitado
503	RATE_UNAVAILABLE	Cotação temporariamente indisponível
500	INTERNAL_ERROR	Erro interno — tente novamente ou contate o suporte

Formato padrão de erro

{
  “error”: “Descrição do erro em português”,
  “code”:  “CODIGO_DO_ERRO”
}

Suporte

Para dúvidas sobre integração, solicitação de sandbox, ou problemas em produção:

Canal	Contato	Horário
E-mail técnico	dev@ckrypto.com.br	Seg–Sex 9h–18h
E-mail geral	contato@ckrypto.com.br	Seg–Sex 9h–18h
Site	ckrypto.com.br	—

✅ CK Serviços Digitais — CNPJ 60.065.974/0001-85 — v1.0 — Maio 2026