Swap (Balance conversion)

Conversion of balance between currencies inside the app (COP ↔ USD, MXN, BRL). It does not send money to bank accounts; it only moves balance between your wallets.

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

🔄

Difference from Exchange (FX): Exchange is for cross-border movements (quote and send to bank). Swap is for converting internal balance 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
USD → MXN, MXN → USD
USD → BRL, BRL → 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	Natural persons	Immediate conversion. Balance is debited and credited instantly in main wallet (MAIN).
QUOTE	Legal entities	Requires operator approval. Balance is reserved in quotation wallet (QUOTATION) and credited when approved.

General flow

Create quote

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

Execute conversion

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

For SWAP the conversion is applied immediately. For QUOTE the balance remains reserved until an operator approves the quote.

Step 1: Create quote

Returns the exchange rate and resulting amount for the conversion. It does not execute the operation.

Endpoint

POST /quote/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Content-Type: application/json
Accept: application/json

Request

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

USD to COP

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

COP to USD

{
  "currency_from": "COP",
  "currency_to": "USD",
  "source_amount": 407731.25,
  "action": "SWAP"
}

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"
  }'

Success response (200)

200 OK

{
  "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
  }
}

Field	Description
`id`	Quote ID. Use in `POST /swap/` as `quote_id`.
`rate`	Exchange rate applied
`source_amount`	Amount in source currency
`target_amount`	Amount you will receive in destination currency
`fee_amount`, `fee_iva_amount`	Fees (if any)

💾

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

Step 2: Execute conversion

Executes the conversion using the quote ID from step 1.

Endpoint

POST /swap/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Content-Type: application/json
Accept: application/json

Request

Field	Type	Required	Description
`quote_id`	integer	✅	Quote ID from step 1
`action`	string	✅	Same action as in the quote: `SWAP` or `QUOTE`
`ip`	string	✅	Client IP
`latitude`	string	✅	GPS latitude
`longitude`	string	✅	GPS longitude

request.json

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

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"
  }'

Success response (200)

200 OK

{
  "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 is updated immediately. With QUOTE the amount remains reserved until operator approval.

Supported pairs

Pair	Description
USD → COP	US dollars to Colombian pesos
COP → USD	Colombian pesos to US dollars
USD → MXN	US dollars to Mexican pesos
MXN → USD	Mexican pesos to US dollars
USD → BRL	US dollars to Brazilian reais
BRL → USD	Brazilian reais to US dollars

Rates are updated periodically by the system.

Internal process (summary)

SWAP (immediate)

Balance is debited from the source currency in the main wallet (MAIN).
Balance is credited to the destination currency in the main wallet (MAIN).
Fees are recorded in Colurs fee wallet.

QUOTE (with approval)

Balance is debited from the source currency in the quotation wallet (QUOTATION).
Operator approval is awaited.
On approval, balance is credited to the destination currency in the quotation wallet (QUOTATION).

Each conversion creates balance movements with reason SWAP.

📊

You can check your balance per currency with the Balance endpoints to verify balances before and after conversion.

Exchange (FX)Send (P2P transfers)