Swap (Balance conversion)

Instantly converts balance between different user wallets.

All endpoints require authentication with Authorization: Bearer [TOKEN] and x-api-key.

🔄

Difference vs Exchange (FX): Exchange is for cross-border movements (quote and send to bank). Swap is for internal balance conversion between your currencies in Colurs.

Overview

What is Swap?

The Swap module lets you convert balance from one currency to another within your Colurs account:

USD → COP, COP → USD

Balance is debited from the source currency and credited to the destination currency in your wallet.

Two conversion modes

Mode	Typical use	Behavior
SWAP	Individual users	Immediate conversion. Debits and credits instantly in main wallet (MAIN).
QUOTE	Business users	Requires operator approval. Funds are reserved in quote wallet (QUOTATION) and credited after approval.

General flow

Create quote

Get rate and target amount with POST /quote/ (action SWAP or QUOTE).

Execute conversion

Confirm operation with POST /swap/ using quote_id from step 1.

For SWAP, conversion is applied instantly. For QUOTE, funds remain reserved until an operator approves the quote.

Exchange rate

Gets the rate between two fiat currencies (COP ↔ USD) for SWAP action.

POST /exchange_rate/

Body: currency_from (e.g. COP, USD), currency_to (e.g. USD, COP), source_amount (number), action: “SWAP”.

Gets the exchange rate and resulting amount for conversion. Does not execute the operation.

Step 1: Create quote

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

POSThttps://api.colurs.co/quote/

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Field	Type	Required	Description
currency_from	string	✓	Source currency: USD, COP
currency_to	string	✓	Destination currency: COP, USD
source_amount	number	✓	Amount to convert in source currency
action	string	✓	SWAP (immediate) or QUOTE (requires approval)

request.json{
"currency_from": "USD",
"currency_to": "COP",
"source_amount": 100000,
"action": "SWAP"
}

cURL Example

curl -X POST "https://api.colurs.co/quote/" \
-H "Authorization: Bearer [TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{
  "currency_from": "USD",
  "currency_to": "COP",
  "source_amount": 100000,
  "action": "SWAP"
}'

Response

response.json

{
"message": "OK",
"data": {
  "id": 688,
  "user": "colurs@colurs.io",
  "currency_from": "USD",
  "currency_to": "COP",
  "rate": 4077.3125550239233,
  "fee_amount": 0.0,
  "fee_iva_amount": 0.0,
  "source_amount": 100000.0,
  "target_amount": 407731250.0,
  "total_paid": 100000.0
}
}

💾

Save quote `id` for the next step. Quote must be used with the same `action` (SWAP or QUOTE).

Executes conversion using the quote ID created in step 1.

Step 2: Execute conversion

Authorizations

Both x-api-key and Authorization: Bearer <token> headers are required.

Endpoint

POSThttps://api.colurs.co/swap/

Required Headers

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Field	Type	Required	Description
quote_id	integer	✓	Quote ID (step 1)
action	string	✓	Same action used in quote: SWAP or QUOTE
ip	string	✓	Client IP
latitude	string	✓	Latitude GPS
longitude	string	✓	Longitude GPS

request.json{
"quote_id": 688,
"action": "SWAP",
"ip": "192.168.1.1",
"latitude": "4.60971",
"longitude": "-74.08175"
}

cURL Example

curl -X POST "https://api.colurs.co/swap/" \
-H "Authorization: Bearer [TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{
  "quote_id": 688,
  "action": "SWAP",
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175"
}'

Response

response.json

{
"message": "OK",
"data": {
  "id": 1688,
  "user": "colurs@colurs.io",
  "currency_from": "USD",
  "currency_to": "COP",
  "rate": 4077.3125550239233,
  "fee_amount": 0.0,
  "fee_iva_amount": 0.0,
  "source_amount": 100000.0,
  "target_amount": 407731250.0
}
}

With SWAP, balance updates immediately. With QUOTE, amount stays reserved until operator approval.

Fast swap

Creates an ID for quick conversion (used in flows like UMA when applicable).

POST /fast_swap/

Body: currency_from_code (e.g. COP), currency_to_code (e.g. USD).

Pares soportados

Par	Description
USD → COP	US dollars to Colombian pesos
COP → USD	Colombian pesos to US dollars

Rates are updated periodically by the system.

Internal process (summary)

SWAP (immediate)

Source currency balance is debited in main wallet (MAIN).
Destination currency balance is credited in main wallet (MAIN).
Fees are recorded in Colurs wallet.

QUOTE (with approval)

Source currency balance is debited in quote wallet (QUOTATION).
Wait for operator approval.
After approval, destination balance is credited in quote wallet (QUOTATION).

Each conversion generates balance movements with reason SWAP.

📊

You can check your balance by currency using Balance endpoints to verify before and after conversion.

Mexico exchange (MXN)How to manage bank accounts