Skip to main content

​
Welcome to Mueve API

This quickstart guide will walk you through the complete workflow of using the Mueve currency exchange API, from registration to creating your first transaction. You’ll learn how to:
  • Register a new user account
  • Authenticate and obtain a JWT token
  • Get the current exchange rate
  • Create a currency exchange transaction
The Mueve API is a RESTful API that runs on http://localhost:3001 by default. All endpoints return JSON responses.

​
Prerequisites

Before you begin, make sure you have:
  • A tool for making HTTP requests (curl, Postman, or similar)
  • Basic understanding of REST APIs and JSON
  • The API base URL: http://localhost:3001/api

​
Complete Workflow

1

Register a New User

First, create a user account by sending a POST request to the /register endpoint.
curl -X POST http://localhost:3001/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "securePassword123"
  }'
​
name
string
required
The full name of the user
​
email
string
required
A valid email address (must be unique)
​
password
string
required
User password (will be encrypted using bcrypt)
If the email is already registered, you’ll receive a 400 status with the message: “El email ya está registrado”
2

Login and Get Authentication Token

After registration, authenticate to receive a JWT token that you’ll use for protected endpoints.
curl -X POST http://localhost:3001/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securePassword123"
  }'
​
message
string
Success message
​
token
string
JWT authentication token (valid for 24 hours)
​
user
object
User information object
​
user.id
number
Unique user identifier
​
user.name
string
User’s full name
​
user.email
string
User’s email address
Save your token! You’ll need to include this JWT token in the Authorization header for all authenticated requests.
3

Get Current Exchange Rate

Before creating a transaction, fetch the current USD to BsF (Bolívar) exchange rate.
curl -X GET http://localhost:3001/api/rate
This endpoint does not require authentication. The rate is fetched from Redis cache with a database fallback.
The rate represents how many Bolívares (BsF) you get for 1 USD:
  • Rate: 45.67 means 1 USD = 45.67 BsF
  • When buying USD: You pay BsF to receive USD
  • When selling USD: You receive BsF for your USD
The rate is automatically updated and persisted to ensure accuracy.
4

Create Your First Transaction

Now you’re ready to create a currency exchange transaction. You can either buy or sell USD.
curl -X POST http://localhost:3001/api/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "transaction_type": "Comprar",
    "amount_usd": 20.00,
    "rate_bs": 45.67,
    "payment_reference": "REF123456789",
    "type_pay": "Pago Movil",
    "recipient_account": "0414-1234567"
  }'
​
transaction_type
string
required
Type of transaction: "Comprar" (buy USD) or "Vender" (sell USD)
​
amount_usd
number
required
Amount in USD to exchange (must be positive)
​
rate_bs
number
required
Current exchange rate (must be within 0.35 tolerance of actual rate)
​
payment_reference
string
required
Unique payment reference number (cannot be reused)
​
type_pay
string
Payment method (e.g., “Pago Movil”, “Transferencia”, “Zelle”)
​
recipient_account
string
Account number or phone number for payment
The Mueve API automatically calculates commissions based on the transaction amount:
Amount Range (USD)Commission (USD)
1−1 - 9.99$0.80
10−10 - 14.99$1.00
15−15 - 25$1.40
Over $25$1.40 + 8% of excess
For Buy transactions (Comprar):
  • Total USD = Amount + Commission
  • Total BsF = Total USD × Rate
For Sell transactions (Vender):
  • Total USD = Amount - Commission
  • Total BsF = Total USD × Rate
Important validations:
  • The rate must be within 0.35 tolerance of the current rate
  • Payment references cannot be reused
  • For sell transactions, commission cannot exceed the amount
  • All authenticated requests require the Bearer token in the Authorization header
5

Retrieve Transaction Details

After creating a transaction, you can retrieve its details or list all your transactions.
curl -X GET http://localhost:3001/api/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Transactions are returned in descending order by creation date, with the most recent first.

​
Authentication Flow Summary

Here’s a quick reference for the authentication flow: 
// 1. Register (one-time)
const registerResponse = await fetch('http://localhost:3001/api/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name, email, password })
});

// 2. Login (get token)
const loginResponse = await fetch('http://localhost:3001/api/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password })
});
const { token } = await loginResponse.json();

// 3. Use token for authenticated requests
const response = await fetch('http://localhost:3001/api/transactions', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});
JWT tokens expire after 24 hours. When your token expires, simply login again to get a new one.

​
Common Error Responses

Here are the most common errors you might encounter:
Missing required fields:
{ "message": "Todos los campos son obligatorios" }
Email already registered:
{ "message": "El email ya está registrado" }
Rate changed:
{ "message": "La tasa ha cambiado. Por favor actualiza la página para continuar." }
No token provided:
{ "message": "No se proporcionó token" }
Invalid credentials:
{ "message": "Credenciales inválidas" }
Invalid or expired token:
{ "message": "Token inválido o expirado" }
Transaction not found:
{ "message": "Transacción no encontrada" }
Duplicate payment reference:
{ "message": "La referencia de pago ya fue utilizada" }
Server error:
{ "message": "Error del servidor" }

​
Next Steps

Now that you’ve completed your first transaction, explore more features:

Authentication Details

Learn more about JWT authentication and security

Exchange Rates

Understand how rates are fetched and updated

Transactions

Deep dive into transaction types and workflows

Commission Structure

Learn how commissions are calculated
Need help? Check out the complete API Reference for detailed endpoint documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us