📖 Ramp Transfero Tools API

Base URL

https://ramp.transfero.tools/

Interactive Documentation

Test all endpoints live in our interactive documentation:

Swagger UI - Interactive API testing
ReDoc - Clean documentation view

Authentication Overview

This API uses dual authentication for maximum security:

Bearer Token - Only for API key management (create/list/delete keys)
API Key Signatures - For all business operations (clients, transactions)

Quick Auth Setup

# 1. Get Bearer token (only for key management)
curl -X POST https://ramp.transfero.tools/v1/auth/token \
  -d '{"username": "your_username", "password": "your_password"}'

# 2. Register API key (uses Bearer token)
curl -X POST https://ramp.transfero.tools/v1/api-keys \
  -H "Authorization: Bearer your_token" \
  -d '{"name": "Production Key", "public_key": "...", "signature": "..."}'

# 3. Use API key for all other operations (no Bearer token needed)
curl -X POST https://ramp.transfero.tools/v1/clients/ \
  -H "X-API-Key: your_key_hash" \
  -H "X-API-Timestamp: timestamp" \
  -H "X-API-Signature: signature" \
  -d '{"name": "Client Name", "email": "[email protected]", "tax_id": "12345678901"}'

👉 Complete Authentication Guide

Core Workflow

1. Client Management

First, register your end-users as "clients" (using API key signatures):

POST /v1/clients/
Headers:
  X-API-Key: your_key_hash
  X-API-Timestamp: 1716451200000
  X-API-Signature: your_signed_request

Body:
{
  "name": "João Silva",
  "email": "[email protected]", 
  "tax_id": "12345678901"
}

2. PIX In (BRL → Crypto)

User pays BRL via PIX, receives crypto (using API key signatures):

POST /v1/pix-in-requests
Headers:
  X-API-Key: your_key_hash
  X-API-Timestamp: 1716451200000
  X-API-Signature: your_signed_request

Body:
{
  "amount_brl": "100.00",
  "to_currency": "USDC",
  "blockchain": "Ethereum",
  "wallet_address": "0x742d35Cc6600C187...",
  "external_id": "123abc",
  "client_email": "[email protected]"
}

Response includes:

PIX QR Code for payment
PIX Copia e Cola string
Transaction tracking ID

3. PIX Out (Crypto → BRL)

User sends crypto, receives BRL via PIX (using API key signatures):

POST /v1/pix-out-requests
Headers:
  X-API-Key: your_key_hash
  X-API-Timestamp: 1716451200000
  X-API-Signature: your_signed_request

Body:
{
  "from_amount": "95.50",
  "from_currency": "USDC", 
  "deposit_blockchain": "Ethereum",
  "pix_key": "123",
  "external_id": "123abc",
  "client_email": "[email protected]"
}

Response includes:

Unique crypto deposit address
QR code for easy scanning
Estimated BRL amount

API Endpoints Reference

All endpoints are prefixed with /v1/

Authentication

Method	Endpoint	Description
`POST`	`/auth/token`	Get Bearer token

API Key Management

Method	Endpoint	Description	Auth Required
`POST`	`/api-keys`	Register new API key	Bearer
`GET`	`/api-keys`	List your API keys	Bearer
`DELETE`	`/api-keys/<key_hash>`	Delete API key	Bearer

Client Management

Authentication Requirements by Endpoint

Endpoint	Bearer Token	API Signature
`POST /auth/token`	❌	❌
`POST /api-keys`	✅	❌
`GET /api-keys`	✅	❌
`DELETE /api-keys/<hash>`	✅	❌
All client endpoints	❌	✅
All transaction endpoints	❌	✅

Query Parameters for GET /clients/:

[email protected] - Filter by email

PIX In (BRL → Crypto)

Method	Endpoint	Description	Auth Required
`POST`	`/pix-in-requests`	Create PIX-to-crypto order	API Signature
`GET`	`/pix-in-requests`	Get transaction history	API Signature

PIX In Request Body:

{
  "amount_brl": "string",
  "to_currency": "BRL",
  "blockchain": "Ethereum",
  "wallet_address": "string",
  "external_id": "string",
  "client_email": "[email protected]"
}

PIX In Response Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user": "string",
  "client": "string",
  "amount_brl": "string",
  "to_currency": "string",
  "blockchain": "string",
  "wallet_address": "string",
  "transfero_reference_id": "string",
  "external_id": "string",
  "status": "string",
  "qr_code": "string",
  "br_code": "string",
  "blockchain_fee": "string",
  "created_at": "2025-05-25T11:30:21.696Z",
  "updated_at": "2025-05-25T11:30:21.696Z",
  "completed_at": "2025-05-25T11:30:21.696Z"
}

PIX Out (Crypto → BRL)

Method	Endpoint	Description	Auth Required
`POST`	`/pix-out-requests`	Create crypto-to-PIX order	API Signature
`GET`	`/pix-out-requests`	Get transaction history	API Signature

PIX Out Request Body:

{
  "from_currency": "BRL",
  "from_amount": "string",
  "deposit_blockchain": "Ethereum",
  "pix_key": "string",
  "external_id": "string",
  "client_email": "[email protected]"
}

PIX Out Response Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "user": "string",
  "client": "string",
  "from_currency": "string",
  "from_amount": "string",
  "to_currency": "string",
  "to_amount_brl": "string",
  "pix_key": "string",
  "deposit_address": "string",
  "wallet_address": "string",
  "qr_code": "string",
  "transfero_quote_id": "string",
  "transfero_reference_id": "string",
  "external_id": "string",
  "rate": "string",
  "blockchain_fee": "string",
  "status": "string",
  "created_at": "2025-05-25T11:30:21.699Z",
  "updated_at": "2025-05-25T11:30:21.699Z",
  "completed_at": "2025-05-25T11:30:21.699Z"
}

History Query Parameters:

?status=PixPaymentPending - Filter by status
[email protected] - Filter by client
?external_id=your_ref - Filter by your reference ID

Supported Cryptocurrencies

BRZ (Brazilian Digital Token)
ETH (Brazilian Digital Token)
USDC (USD Coin)
USDT (Tether)
DAI

Supported Blockchains

Ethereum
Polygon
Gnosis

Transaction States

PIX In/Out States

SwapOrderCreated - Awaiting crypto deposit or PIX in
DepositReceived - When the initial deposit for the ramp has been received.
TradeCompleted - When the trade process between parties has been successfully executed.
WithdrawalCreated - In on-ramp and off-ramp processes, this indicates the start of the withdrawal process.
WithdrawalProcessing - The ongoing withdrawal process.
WithdrawalCompleted - When the withdrawal process is successfully completed.
SwapOrderCompleted - BRL sent via PIX or crypto sent to user's wallet
SwapOrderError - Transaction failed

Error Handling

All errors return consistent JSON format:

{
  "error": "Description of what went wrong"
}

Common HTTP status codes:

400 - Invalid request data
401 - Authentication failed
404 - Resource not found
500 - Server error

Security Notes

Keep your private key secure and never expose it
Use HTTPS for all requests
Regularly rotate your API keys

Rate Limiting

Standard rate limits apply. Contact support if you need higher limits for production use.

Support

Interactive Testing: Swagger UI
Documentation: ReDoc
Authentication Help: Authentication Guide