Intermediário 20 min

CaaS: Sua primeira operação

Neste guia você vai autenticar na API CaaS, consultar mercados e executar sua primeira ordem de compra/venda de criptoativos. A API CaaS permite operar em múltiplas exchanges através de uma única integração.

Visão geral

O CaaS (Crypto as a Service) é uma plataforma B2B que permite que empresas ofereçam compra e venda de criptoativos para seus clientes sem precisar integrar diretamente com exchanges. A Liqi conecta sua aplicação à Binance, Foxbit e outras exchanges via uma API unificada.

Importante

A API CaaS v1 usa autenticação JWT. Você receberá um apiKey e um secretKey no onboarding.

1Obter token JWT

Autentique-se com suas credenciais para obter um token JWT. Esse token deve ser enviado em todas as requisições seguintes no header Authorization.

cURL

curl -X POST "https://caas.liqi.com.br/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "sua-api-key",
    "secretKey": "sua-secret-key"
  }'

Resposta

{
  "accessToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600
}

Node.js

const BASE_URL = "https://caas.liqi.com.br/v1";

const auth = await fetch(`${BASE_URL}/auth/login`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: process.env.CAAS_API_KEY,
    secretKey: process.env.CAAS_SECRET_KEY,
  }),
}).then((r) => r.json());

const token = auth.accessToken;
console.log("Token obtido, expira em:", auth.expiresIn, "segundos");

// Use em todas as requisições:
const headers = {
  Authorization: `Bearer ${token}`,
  "Content-Type": "application/json",
};

Dica

O token expira em 1 hora. Use o refreshToken via PUT /v1/auth/refresh para renovar sem precisar reautenticar.

2Criar perfil de cliente

Antes de operar, crie um perfil para o cliente final. Cada perfil representa uma pessoa física ou jurídica que irá operar pela sua plataforma.

cURL

curl -X POST "https://caas.liqi.com.br/v1/account/createProfile" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João da Silva",
    "document": "12345678900",
    "documentType": "CPF",
    "email": "joao@exemplo.com"
  }'

Resposta

{
  "id": "profile_abc123",
  "name": "João da Silva",
  "document": "12345678900",
  "status": "ACTIVE",
  "walletId": "wallet_xyz789",
  "createdAt": "2026-02-21T10:00:00Z"
}

3Verificar saldo da wallet

Consulte o saldo disponível na wallet do cliente antes de criar uma ordem.

cURL

curl -s "https://caas.liqi.com.br/v1/wallet/fetchBalance" \
  -H "Authorization: Bearer {token}"

Resposta

{
  "wallets": [
    {
      "currency": "BRL",
      "available": "10000.00",
      "locked": "0.00",
      "total": "10000.00"
    },
    {
      "currency": "BTC",
      "available": "0.05000000",
      "locked": "0.00000000",
      "total": "0.05000000"
    },
    {
      "currency": "USDT",
      "available": "500.00",
      "locked": "0.00",
      "total": "500.00"
    }
  ]
}

4Consultar mercados

Liste os pares de negociação disponíveis e consulte preços em tempo real.

Listar mercados

curl -s "https://caas.liqi.com.br/v1/market/fetchMarkets" \
  -H "Authorization: Bearer {token}"

Resposta

{
  "markets": [
    {
      "symbol": "BTC/BRL",
      "baseCurrency": "BTC",
      "quoteCurrency": "BRL",
      "minOrderSize": "0.00001",
      "priceDecimals": 2,
      "amountDecimals": 8,
      "status": "ACTIVE"
    },
    {
      "symbol": "ETH/BRL",
      "baseCurrency": "ETH",
      "quoteCurrency": "BRL",
      "minOrderSize": "0.0001",
      "priceDecimals": 2,
      "amountDecimals": 8,
      "status": "ACTIVE"
    }
  ]
}

Consultar ticker (preço atual)

curl -s "https://caas.liqi.com.br/v1/market/fetchTicker?symbol=BTC/BRL" \
  -H "Authorization: Bearer {token}"

Resposta

{
  "symbol": "BTC/BRL",
  "bid": "520000.00",
  "ask": "520150.00",
  "last": "520075.00",
  "volume24h": "12.5",
  "change24h": "2.35",
  "timestamp": "2026-02-21T14:30:00Z"
}

5Executar ordem a mercado

Crie uma ordem de compra (ou venda) a mercado. A ordem será executada imediatamente ao melhor preço disponível nas exchanges conectadas.

cURL

curl -X POST "https://caas.liqi.com.br/v1/orders/createOrder" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC/BRL",
    "side": "BUY",
    "type": "MARKET",
    "quoteAmount": "1000.00"
  }'

Resposta

{
  "orderId": "ord_abc123def456",
  "symbol": "BTC/BRL",
  "side": "BUY",
  "type": "MARKET",
  "status": "FILLED",
  "quoteAmount": "1000.00",
  "filledAmount": "0.00192280",
  "averagePrice": "520075.00",
  "fee": "2.50",
  "feeCurrency": "BRL",
  "createdAt": "2026-02-21T14:30:00Z",
  "filledAt": "2026-02-21T14:30:01Z"
}

Campo	Descrição
symbol	Par de negociação (ex: BTC/BRL)
side	BUY ou SELL
type	MARKET (execução imediata) ou LIMIT
quoteAmount	Valor em moeda cotação (BRL) para ordens de compra
amount	Quantidade da moeda base para ordens de venda
filledAmount	Quantidade efetivamente executada
averagePrice	Preço médio de execução

6Verificar status da ordem

Ordens a mercado geralmente são preenchidas imediatamente, mas você pode verificar o status a qualquer momento.

cURL

curl -s "https://caas.liqi.com.br/v1/orders/fetchOrder?orderId=ord_abc123def456" \
  -H "Authorization: Bearer {token}"

Status	Descrição
PENDING	Ordem criada, aguardando execução
PARTIALLY_FILLED	Ordem parcialmente executada
FILLED	Ordem totalmente executada
CANCELLED	Ordem cancelada
REJECTED	Ordem rejeitada pela exchange

RFQ: Cotações para melhores preços

Para operações de maior valor, use o fluxo de RFQ (Request for Quote) para obter uma cotação fixa antes de executar. Isso garante o preço exato sem risco de slippage.

1. Solicitar cotação

curl -X POST "https://caas.liqi.com.br/v1/orders/rfq/createQuote" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC/BRL",
    "side": "BUY",
    "quoteAmount": "50000.00"
  }'

Resposta da cotação

{
  "quoteId": "qt_xyz789",
  "symbol": "BTC/BRL",
  "side": "BUY",
  "price": "519850.00",
  "amount": "0.09618432",
  "quoteAmount": "50000.00",
  "fee": "125.00",
  "feeCurrency": "BRL",
  "expiresAt": "2026-02-21T14:30:30Z",
  "ttlSeconds": 30
}

2. Consultar cotação (opcional)

curl -s "https://caas.liqi.com.br/v1/orders/rfq/fetchQuote?quoteId=qt_xyz789" \
  -H "Authorization: Bearer {token}"

3. Executar a cotação

curl -X POST "https://caas.liqi.com.br/v1/orders/rfq/createOrder" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "qt_xyz789"
  }'

Atenção

Cotações RFQ expiram em 30 segundos. Execute a ordem antes da expiração ou solicite uma nova cotação.

Modo sandbox

Use o header X-Synthetic: true para operar em modo sandbox. Nesse modo, as ordens são simuladas e não afetam saldos reais. Ideal para testar sua integração.

cURL (sandbox)

curl -X POST "https://caas.liqi.com.br/v1/orders/createOrder" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "X-Synthetic: true" \
  -d '{
    "symbol": "BTC/BRL",
    "side": "BUY",
    "type": "MARKET",
    "quoteAmount": "1000.00"
  }'

Dica

Ordens sintéticas retornam preços reais de mercado, mas nenhum trade é executado. Perfeito para validar seu fluxo antes de ir para produção.

Diagrama de sequência

Fluxo completo de uma ordem a mercado:

CaaS — Fluxo de Ordem a Mercado

Próximos passos

Configurar Webhooks

Receba notificações de order.filled e deposit.confirmed

Verificação de Webhooks

Valide assinaturas HMAC-SHA256 dos webhooks

Rate Limits

Entenda os limites por endpoint

API Reference

Documentação completa de todas as APIs