Mexico exchange (MXN)

Perform currency conversions between MXN and USD within the platform.

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

💡

Difference vs other modules: - Exchange (FX): Cross-border movements between fiat currencies (USD/COP/PEN/CLP) with payout to bank accounts.

Swap: Internal balance conversion between wallets (COP ↔ USD) without external transfer. - Exchange MXN: Asset conversion via RFQ (MXN ↔ USDT, BTC, etc.) with quote and immediate execution.

Key concepts

Conversion states

Status	Description
`INITIATED`	Conversion created, in process
`COMPLETED`	Conversion executed successfully
`FAILED`	Conversion failed
`TERMINATED`	Conversion canceled/terminated

Operation types (trade type)

Type	Description
`BUY`	Buy destination asset using source currency
`SELL`	Sell source asset to receive destination currency

Quote scenarios

Scenario	Direction	Amount	Description
1	Canonical	from_amount	Sell exact source currency amount
2	Canonical	to_amount	Calculate required source amount to receive target amount
3	Inverse	from_amount	Buy destination asset using exact source amount
4	Inverse	to_amount	Calculate required source amount to buy target amount

General flow

Check available pairs

Get RFQ conversion pairs with GET /exchange/pairs.

(Optional) Preview

Get quote without execution using POST /exchange/conversions/preview to show rate and amount to the user.

Create conversion

Request quote and execute conversion with POST /exchange/conversions.

Check status

Check result with GET /exchange/conversions/{profile_uuid}/{conversion_identifier}.

Available pairs

Lists available RFQ conversion pairs. This endpoint queries the conversions service directly.

Available Conversion Pairs

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/pairs

Required Headers

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

Request Body

Field	Type	Required	Description
from_currency	string	✕	Filter by source currency/asset (e.g. mxn, usdt)
to_currency	string	✕	Filter by destination currency/asset (e.g. btc, mxn)

request.json?from_currency=mxn

cURL Example

curl -X GET "https://dev.backend.colurs.co/exchange/pairs?from_currency=mxn" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Response

response.json

{
"code_transaction": "OK",
"data": {
  "pairs": [
    { "from_currency": "mxn", "to_currency":  "usdt"},
    { "from_currency": "mxn", "to_currency":  "btc"},
    { "from_currency": "usdt", "to_currency":  "mxn"},
    { "from_currency": "btc", "to_currency":  "mxn"}
  ]
}
}

Conversions

Conversion preview

Gets an RFQ quote in preview format without executing or persisting the conversion. Useful to show destination amount and rate before confirmation.

Conversion preview

Authorizations

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

Endpoint

POSThttps://dev.backend.colurs.co/exchange/conversions/preview

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✓	User profile UUID
from_currency	string	✓	Source currency/asset (e.g. mxn)
to_currency	string	✓	Destination currency/asset (e.g. usdt)
from_amount	decimal	⚠	Amount in source currency (send from_amount or to_amount)
to_amount	decimal	⚠	Amount in destination currency (send from_amount or to_amount)
trade_type	string	✓	Operation type: 'BUY' or 'SELL'
asset	string	✕	Involved asset (e.g. usdt, btc)

request.json{
"profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
"from_currency": "mxn",
"to_currency": "usdt",
"from_amount": "10000.00",
"trade_type": "BUY",
"asset": "usdt"
}

cURL Example

curl -X POST "https://dev.backend.colurs.co/exchange/conversions/preview" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"profile_uuid":"550e8400-e29b-41d4-a716-446655440000","from_currency":"mxn","to_currency":"usdt","from_amount":"10000.00","trade_type":"BUY"}'

Response

response.json

{
"code_transaction": "OK",
"data": {
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "conversion_identifier": null,
  "from_currency": "mxn",
  "to_currency": "usdt",
  "asset": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "quote_identifier": "quote_xyz",
  "exchange_rate": "17.2343",
  "conversion_status": "INITIATED",
  "quote_created_at": "2026-02-15T14:30:00Z",
  "conversion_created_at": null,
  "conversion_updated_at": null,
  "conversion_scenario": {
    "scenario_number": 1,
    "trade_type": "BUY",
    "interpretation": 
  "Sell exact source currency amount"}
}
}

Possible Errors

Code	Error	Description
400	BadRequest	Invalid conversion pair or invalid amounts
400	BadRequest	Both from_amount and to_amount sent simultaneously
500	InternalError	Error communicating with quote service

This endpoint **does not create** the conversion or debit balance. It only returns the current quote. To execute conversion use `POST /exchange/conversions`.

Create conversion

Requests an RFQ quote and executes it immediately. Conversion is persisted in the local database associated with profile_uuid.

Create Conversion

Authorizations

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

Endpoint

POSThttps://dev.backend.colurs.co/exchange/conversions

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✓	User profile UUID
from_currency	string	✓	Source currency/asset (e.g. mxn)
to_currency	string	✓	Destination currency/asset (e.g. usdt)
from_amount	decimal	⚠	Amount in source currency (send from_amount or to_amount)
to_amount	decimal	⚠	Amount in destination currency (send from_amount or to_amount)
trade_type	string	✓	Operation type: 'BUY' or 'SELL'
asset	string	✕	Involved asset (e.g. usdt, btc)

request.json{
"profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
"from_currency": "mxn",
"to_currency": "usdt",
"from_amount": "10000.00",
"trade_type": "BUY",
"asset": "usdt"
}

cURL Example

curl -X POST "https://dev.backend.colurs.co/exchange/conversions" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"profile_uuid":"550e8400-e29b-41d4-a716-446655440000","from_currency":"mxn","to_currency":"usdt","from_amount":"10000.00","trade_type":"BUY"}'

Response

response.json

{
"code_transaction": "OK",
"data": {
  "conversion_identifier": "conv_abc123xyz",
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from_currency": "mxn",
  "to_currency": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "rate": "17.2343",
  "trade_type": "BUY",
  "scenario_number": 1,
  "conversion_state": "COMPLETED",
  "created_at": 
"2026-02-15T14:30:00Z"}
}

Possible Errors

Code	Error	Description
400	BadRequest	Invalid conversion pair or invalid amounts
400	BadRequest	Both from_amount and to_amount sent simultaneously
402	InsufficientFunds	Insufficient balance for conversion
500	InternalError	Error communicating with conversions service

⚠️

You must send **only one** of `from_amount` or `to_amount`. Quote scenario is calculated automatically based on direction and amount type.

List conversions

List all conversions from local database using cursor pagination.

List Conversions

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/conversions

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✕	Filter by profile UUID
asset	string	✕	Filter by asset (e.g. usdt, btc)
conversion_state	string	✕	Filter by state: COMPLETED, FAILED, INITIATED, TERMINATED
page_limit	integer	✕	Results per page (default: 20, max: 100)
pagination_cursor	string	✕	Opaque cursor from previous response for pagination

request.json?conversion_state=COMPLETED&page_limit=10

cURL Example

curl -X GET "https://dev.backend.colurs.co/exchange/conversions?conversion_state=COMPLETED&page_limit=10" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Response

response.json

{
"code_transaction": "OK",
"data": {
  "conversions": [
    {
      "conversion_identifier": "conv_abc123xyz",
      "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "from_currency": "mxn",
      "to_currency": "usdt",
      "from_amount": "10000.00",
      "to_amount": "580.25",
      "rate": "17.2343",
      "trade_type": "BUY",
      "conversion_state": "COMPLETED",
      "created_at": 
    "2026-02-15T14:30:00Z"}
  ],
  "pagination_cursor": "eyJpZCI6MTIzfQ==",
  "has_more": true
}
}

💡

Use `pagination_cursor` from the response as a parameter in the next request to get more results.

List user conversions

List conversions for a specific user from local database. It does not query external service.

User Conversions

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/conversions/user/{profile_uuid}

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✓	User profile UUID (path param)
asset	string	✕	Filter by asset
conversion_state	string	✕	Filter by state: COMPLETED, FAILED, INITIATED, TERMINATED

request.json/exchange/conversions/user/550e8400-e29b-41d4-a716-446655440000?conversion_state=COMPLETED

cURL Example

curl -X GET "https://dev.backend.colurs.co/exchange/conversions/user/550e8400-e29b-41d4-a716-446655440000?conversion_state=COMPLETED" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Response

response.json

{
"code_transaction": "OK",
"data": {
  "conversions": [
    {
      "conversion_identifier": "conv_abc123xyz",
      "from_currency": "mxn",
      "to_currency": "usdt",
      "from_amount": "10000.00",
      "to_amount": "580.25",
      "rate": "17.2343",
      "trade_type": "BUY",
      "conversion_state": "COMPLETED",
      "created_at": 
    "2026-02-15T14:30:00Z"}
  ]
}
}

Get conversion

Get a specific conversion by identifier. It checks local database first; if not found, it queries the conversions service as fallback.

Get Conversion

Authorizations

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/conversions/{profile_uuid}/{conversion_identifier}

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✓	User profile UUID (path param)
conversion_identifier	string	✓	Conversion identifier (path param)

cURL Example

curl -X GET "https://dev.backend.colurs.co/exchange/conversions/550e8400-e29b-41d4-a716-446655440000/conv_abc123xyz" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Response

response.json

{
"code_transaction": "OK",
"data": {
  "conversion_identifier": "conv_abc123xyz",
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from_currency": "mxn",
  "to_currency": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "rate": "17.2343",
  "trade_type": "BUY",
  "scenario_number": 1,
  "conversion_state": "COMPLETED",
  "asset": "usdt",
  "created_at": 
"2026-02-15T14:30:00Z"}
}

Possible Errors

Code	Error	Description
404	NotFound	Conversion not found in local DB or external service

💡

If conversion is not in local database, the system queries the conversion service automatically.

Manage conversions

Update conversion

Updates asset and trade_type fields for a conversion in local database. scenario_number is recalculated automatically. It does not call external service.

Update Conversion (DB)

Authorizations

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

Endpoint

PATCHhttps://dev.backend.colurs.co/exchange/conversions/{profile_uuid}/{conversion_identifier}

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✓	Profile UUID (path param)
conversion_identifier	string	✓	Conversion identifier (path param)
asset	string	✕	New asset (e.g. usdt, btc)
trade_type	string	✕	New operation type: 'BUY' or 'SELL'

request.json{
"asset": "btc",
"trade_type": "SELL"
}

cURL Example

curl -X PATCH "https://dev.backend.colurs.co/exchange/conversions/550e8400-e29b-41d4-a716-446655440000/conv_abc123xyz" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"asset":"btc","trade_type":"SELL"}'

Response

response.json

{
"code_transaction": "OK",
"data": {
  "conversion_identifier": "conv_abc123xyz",
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from_currency": "mxn",
  "to_currency": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "trade_type": "SELL",
  "asset": "btc",
  "scenario_number": 3,
  "conversion_state": 
"COMPLETED"}
}

Possible Errors

Code	Error	Description
404	NotFound	Conversion not found

⚠️

This endpoint only modifies local record. It does not affect the conversion executed in external service.

Delete conversion

Deletes conversion record from local database. It does not call external service.

Delete Conversion (DB)

Authorizations

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

Endpoint

DELETEhttps://dev.backend.colurs.co/exchange/conversions/{profile_uuid}/{conversion_identifier}

Required Headers

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

Request Body

Field	Type	Required	Description
profile_uuid	uuid	✓	Profile UUID (path param)
conversion_identifier	string	✓	Conversion identifier (path param)

cURL Example

curl -X DELETE "https://dev.backend.colurs.co/exchange/conversions/550e8400-e29b-41d4-a716-446655440000/conv_abc123xyz" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Response

response.json

{
"code_transaction": "OK",
"message": "Conversion deleted successfully",
"data": {}
}

Possible Errors

Code	Error	Description
404	NotFound	Conversion not found

🚫

This action is irreversible. It only deletes local record; conversion executed in external service is not reverted.

Common response fields

Field	Type	Description
`code_transaction`	string	Operation status code
`conversion_identifier`	string	Unique conversion identifier
`profile_uuid`	uuid	User profile UUID
`from_currency`	string	Source currency/asset
`to_currency`	string	Destination currency/asset
`from_amount`	decimal	Amount in source currency
`to_amount`	decimal	Amount in destination currency
`rate`	decimal	Applied exchange rate
`trade_type`	string	BUY or SELL
`scenario_number`	integer	Quote scenario (1-4)
`conversion_state`	string	Conversion state

Important notes

⚠️

Immediate execution: Unlike Exchange FX, which separates quote and execution, Exchange MXN quotes and executes in a single RFQ step.

💡

Local persistence: Conversions are stored locally. PATCH and DELETE endpoints only modify local database and do not affect the real conversion state in external service.

International exchange (FX)Swap (Conversión de saldo)