Documentação da API RAMPIX

Integre pagamentos cripto via Pix em sua aplicação com nossa API robusta e fácil de usar

🚀 Quick Start

Comece a integrar a API RAMPIX em menos de 5 minutos

1
🔑

Obtenha sua API Key

Entre em contato conosco para obter suas credenciais de acesso

x-api-token: YOUR_API_TOKEN
2
💰

Consulte Preços

Use o endpoint de preços para obter cotações em tempo real

POST /price
3
💸

Crie Transações

Implemente onramp e offramp com nossos endpoints

POST /pix/offramp
4
🔔

Configure Webhooks

Receba notificações em tempo real sobre o status

Webhook URL

🔐 Autenticação

Todas as requisições à API requerem autenticação via token

Header de Autenticação

Inclua seu token no header x-api-token em todas as requisições:

Header 
x-api-token: YOUR_API_TOKEN

Segurança

  • ✅ Nunca compartilhe sua API key
  • ✅ Use HTTPS em todas as requisições
  • ✅ Mantenha sua key segura
  • ✅ Monitore o uso da API

🌐 Base URL

URLs base para diferentes ambientes

Produção 🟢 Ativo
https://api.prod.rampix.xyz/api

Use para transações reais e produção

Sandbox 🔴 Em breve
--

Ambiente de testes (em desenvolvimento)

💰 Obter Preços Unificados

Consulte preços atuais para operações onramp e offramp

POST /price

Descrição

Obtenha preços atuais para operações onramp e offramp, incluindo todos os limites e taxas para um token específico.

Request Body

JSON 
{
  "token": "WLD"
}

Parâmetros

Parâmetro Tipo Obrigatório Descrição
token string ✅ Símbolo do token (ex: "WLD", "BTC", "ETH")

Response

JSON 
{
  "success": true,
  "data": {
    "token": "WLD",
    "currency": "BRL",
    "market_price": 2.45,
    "offramp": {
      "price_per_token": 2.40,
      "fee_percentage": 2.0,
      "limits": {
        "max_brl_transaction_amount": 500.0,
        "min_fee_amount": 1.5,
        "max_fee_amount": 500.0
      }
    },
    "onramp": {
      "price_per_token": 2.38,
      "fee_percentage": 3.0,
      "limits": {
        "min_token_transaction_amount": 2.2,
        "max_brl_transaction_amount": 500.0,
        "min_fee_amount": 1.5,
        "max_fee_amount": 500.0
      }
    }
  }
}

🪙 Tokens Suportados

Lista de todos os tokens suportados para trading

GET /price/tokens

Descrição

Obtenha a lista de todos os tokens suportados para trading.

Response

JSON 
{
  "success": true,
  "data": {
    "supportedTokens": [
      {
        "symbol": "WLD",
        "name": "Worldcoin",
        "usdtPair": "WLDUSDT",
        "enabled": true
      }
    ]
  }
}

💸 Criar Transação Offramp

Crie uma transação de saída (offramp) de cripto para PIX

POST /pix/offramp

Descrição

Crie uma transação de saída (offramp) de criptomoedas para PIX.

Request Body

JSON 
{
  "transaction_id": "0x1234567890abcdef...",
  "wallet_address": "0xabcdef1234567890...",
  "token": "WLD",
  "token_amount": 100.5,
  "brl_amount": 245.25,
  "pix_key": "user@example.com"
}

Parâmetros

Parâmetro Tipo Obrigatório Descrição
transaction_id string ✅ Hash da transação blockchain (deve ser único)
wallet_address string ✅ Endereço da carteira que enviou os tokens
token string ✅ Símbolo do token para saída
token_amount number ✅ Quantidade de tokens enviados para nossa carteira
brl_amount number ✅ Valor em BRL para enviar ao usuário (será validado)
pix_key string ✅ Chave PIX para receber o pagamento

Response

JSON 
{
  "success": true,
  "message": "Transaction queued for processing",
  "data": {
    "transaction_id": "56903fe0-881a-4340-96ed-2a0e00bf6481",
    "status": "processing"
  }
}

💳 Criar Transação Onramp

Crie uma transação de entrada (onramp) de PIX para cripto

POST /pix/onramp

Descrição

Crie uma transação de entrada (onramp) de PIX para criptomoedas.

Request Body

JSON 
{
  "wallet_address": "0xabcdef1234567890...",
  "token": "WLD",
  "token_amount": 100.5,
  "brl_amount": 245.25
}

Parâmetros

Parâmetro Tipo Obrigatório Descrição
wallet_address string ✅ Endereço da carteira para receber tokens
token string ✅ Símbolo do token para comprar
token_amount number ✅ Quantidade de tokens que o usuário irá receber, já descontado as fees. (Será validado)
brl_amount number ✅ Valor em BRL para pagar

Response

JSON 
{
  "success": true,
  "message": "Onramp transaction created successfully",
  "data": {
    "transaction_id": "56903fe0-881a-4340-96ed-2a0e00bf6481",
    "qr_code": "00020126580014br.gov.bcb.pix0136...",
    "expiration_date": "2024-01-15T10:35:00.000Z"
  }
}

📊 Status dos Serviços

Verifique se os serviços PIX estão disponíveis

GET /pix/status

Descrição

Verifique se os serviços PIX estão atualmente disponíveis.

Response

JSON 
{
  "success": true,
  "services": {
    "offramp": {
      "available": true,
      "message": "Offramp service available"
    },
    "onramp": {
      "available": true,
      "message": "Onramp service available"
    }
  }
}

📜 Histórico de Transações

Obtenha o histórico de transações para um endereço específico

GET /history/:walletAddress

Descrição

Obtenha o histórico de transações para um endereço de carteira específico.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
walletAddress string ✅ Endereço da carteira para obter histórico (parâmetro URL)

Response

JSON 
{
  "success": true,
  "data": {
    "transactions": [
      {
        "transaction_id": "56903fe0-881a-4340-96ed-2a0e00bf6481",
        "transaction_hash": "0x1234567890abcdef...",
        "status": "COMPLETED",
        "type": "OFFRAMP",
        "amount_brl": 245.25,
        "amount_token": 100.5,
        "token": "WLD",
        "created_at": "2024-01-15T10:30:00.000Z",
        "completed_at": "2024-01-15T10:32:00.000Z"
      }
    ]
  }
}

💡 Exemplos de Integração

Exemplos práticos para diferentes linguagens de programação

Exemplo Completo - cURL

cURL 
# Configurações
API_BASE="https://api.prod.rampix.xyz/api"
API_TOKEN="YOUR_API_TOKEN"

# 1. Obter preços
curl -X POST "${API_BASE}/price" \
  -H "Content-Type: application/json" \
  -H "x-api-token: ${API_TOKEN}" \
  -d '{"token": "WLD"}'

# 2. Criar transação offramp
curl -X POST "${API_BASE}/pix/offramp" \
  -H "Content-Type: application/json" \
  -H "x-api-token: ${API_TOKEN}" \
  -d '{
    "transaction_id": "0x1234...",
    "wallet_address": "0xabcd...",
    "token": "WLD",
    "token_amount": 100.5,
    "brl_amount": 245.25,
    "pix_key": "user@example.com"
  }'

# 3. Criar transação onramp
curl -X POST "${API_BASE}/pix/onramp" \
  -H "Content-Type: application/json" \
  -H "x-api-token: ${API_TOKEN}" \
  -d '{
    "wallet_address": "0xabcd...",
    "token": "WLD",
    "token_amount": 100.5,
    "brl_amount": 245.25
  }'

# 4. Verificar status dos serviços
curl -X GET "${API_BASE}/pix/status" \
  -H "x-api-token: ${API_TOKEN}"

# 5. Obter histórico
curl -X GET "${API_BASE}/history/0xabcd..." \
  -H "x-api-token: ${API_TOKEN}"

🔔 Webhooks

Receba notificações em tempo real sobre mudanças de status

📡

1. Configuração

Configure sua URL de webhook com o nosso suporte.

→
🔄

2. Eventos

Receba notificações sobre mudanças de status

→
✅

3. Confirmação

Retorne 2xx para confirmar recebimento

Estrutura do Payload

JSON 
{
  "transaction_id": "56903fe0-881a-4340-96ed-2a0e00bf6481",
  "transaction_hash": "0x1234567890abcdef...",
  "status": "PROCESSING",
  "type": "OFFRAMP",
  "amount_brl": 245.25,
  "amount_token": 100.5,
  "token": "WLD",
  "pix_key": "user@example.com",
  "processed_at": "2024-01-15T10:30:00.000Z"
}

Headers do Webhook

Header Descrição
Content-Type Sempre application/json
User-Agent Rampix-Webhook/1.0
X-Rampix-Transaction-ID ID interno da transação
X-Rampix-Timestamp Timestamp do webhook

Tipos de Webhook

PROCESSING

Processando

Transação foi enfileirada para processamento PIX

status: "PROCESSING"
COMPLETED

Completado

Pagamento PIX foi confirmado e processado

status: "COMPLETED"
FAILED

Falhou

Transação falhou (verifique error_message)

status: "FAILED"

Lógica de Retry

🔄

Tentativas

Retry de webhooks falhados até 3 vezes

⏱️

Delays

1s, 3s, 5s entre tentativas

⚠️

Limite

Após 3 falhas, não tentamos novamente

❌ Códigos de Erro

Entenda os códigos de erro e como resolvê-los

AUTH_REQUIRED 401

Token de API válido é obrigatório

Solução: Verifique se o header x-api-token está presente e válido
VALIDATION_ERROR 400

Validação da requisição falhou

Solução: Verifique se todos os campos obrigatórios estão preenchidos
INVALID_AMOUNT 400

Valor inválido

Solução: Verifique se o valor está dentro dos limites permitidos
MISSING_TOKEN 400

Parâmetro token é obrigatório

Solução: Inclua o parâmetro token na requisição
UNSUPPORTED_TOKEN 400

Token não é suportado

Solução: Use um token suportado (WLD, USDC, etc.)
INVALID_TYPE 400

Tipo de transação inválido

Solução: Use um tipo válido (ONRAMP ou OFFRAMP)
INVALID_PIX_KEY 400

Formato da chave PIX é inválido

Solução: Use uma chave PIX válida (email, CPF, telefone, etc.)
AMOUNT_LIMITS_ERROR 400

Valor excede os limites

Solução: Verifique os limites mínimos e máximos permitidos
DUPLICATE_TRANSACTION 409

Transação já existe

Solução: Use um transaction_id único para cada transação
SERVICE_BLOCKED 423

Serviço temporariamente indisponível

Solução: Tente novamente em alguns minutos
DEPOSITS_BLOCKED 423

Depósitos temporariamente indisponíveis

Solução: Tente novamente mais tarde
QUEUE_ERROR 500

Falha ao enfileirar transação

Solução: Tente novamente ou entre em contato com suporte
DATABASE_ERROR 500

Erro na operação do banco de dados

Solução: Entre em contato com suporte
QRCODE_ERROR 500

Falha ao gerar QR code

Solução: Tente novamente ou entre em contato com suporte
PRICE_ERROR 500

Falha ao obter preço atual

Solução: Tente novamente ou entre em contato com suporte
INTERNAL_ERROR 500

Erro interno do servidor

Solução: Entre em contato com suporte

🔄 Fluxo de Integração

Entenda como implementar a integração completa

🔑

1. Autenticação

Configure sua API key nos headers

→
💰

2. Consulta Preços

Obtenha preços em tempo real

→
💸

3. Criação Transação

Envie dados para criar transação

→
🔔

4. Webhooks

Receba atualizações de status

🆘 Suporte

Precisa de ajuda? Estamos aqui para você

📧

Email

Entre em contato diretamente com nossa equipe

suporterampix@gmail.com
💬

Comunidade

Conecte-se com outros desenvolvedores

Discord (em breve)