Guides
Dashboard

Order (V2)

Available since API version 2

Suggest Edits

Table of Contents

  1. Prerequisites
  2. What is an Order?
  3. Order States
  4. Simulation
  5. How to Create an Order
  6. Listing Orders
  7. Common Errors

Prerequisites

Before proceeding with this documentation, we recommend reviewing the following topics:

What is an Order?

An order represents a request to buy (Outbound) or sell (Inbound) foreign currency or crypto assets. Orders created via API are first registered, then processed and grouped by the operations team to originate a settlement.

Each order contains all necessary information to ensure the operation is correctly processed, including the amounts involved and details of the parties involved.

Main Properties

counterpartyId

ID of the counterparty that will receive the funds (for BUY operations) or make the payment (for SELL operations).

targetBankChannelId

ID of the bank channel where the operation will be settled.

See the Bank Channels section for more details.

settlementId

ID of the settlement in which the order will be processed.

See the Settlements section for more details.

referenceRate

Reference rate, expressed in BRL, indicating the value of one unit of the foreign currency or crypto asset being traded. It is used to calculate paymentAmount and receivingAmount.

customerRate

Customer rate, representing the referenceRate plus the spread agreed upon with the client.

operation

Type of operation: buy or sell of foreign currency (fiat) or crypto asset.

currencyPair

Represents the currency pair being traded:

  • source: the currency used for payment;
  • target: the currency in which the operation will be settled.

paymentAmount

Amount to be paid by the order initiator:

  • For BUY operations, expressed in BRL;
  • For SELL operations, expressed in the foreign currency or crypto asset.

receivingAmount

Amount to be received by the beneficiary:

  • For BUY operations, expressed in the foreign currency or crypto asset;
  • For SELL operations, expressed in BRL.

currentState

Indicates the current state of the order. For more details, see the Order States section.

Order States

Below are the possible statuses of an order:

StatusDescriptionWebhook Triggered?
CREATEDOrder created, awaiting processing✅
PROCESSEDOrder associated with a settlement✅
CANCELLEDOrder canceled✅
COMPLETEDPayment and settlement completed successfully✅

For payload details, see the Webhooks documentation

Simulation

This feature allows you to simulate a buy or sell order using the same parameters as a real one. The simulation returns estimated payment and receiving amounts, allowing users to make informed decisions before placing an actual order.

How to Create a Simulation

Required parameters:

Optional parameter:

curl --location 'https://faas.dev.tracefinance.io/exchange/api/orders/simulate' --header 'X-Trace-Version: 2' --header 'Content-Type: application/json' --header 'Authorization: Bearer ******' --data '{
    "counterpartyId": "counterparty-uuid",
    "currencyPair": {
        "source": "BRL",
        "target": "USD"
    },
    "amount": {
        "value": "11100",
        "currency": "USD"
    }
}'

Expected response:

{
    "companyId": "company-uuid",
    "counterpartyId": "counterparty-uuid",
    "operation": "BUY",
    "currencyPair": {
        "source": "BRL",
        "target": "USD"
    },
    "paymentAmount": {
        "value": 82509,
        "currency": "BRL",
        "decimals": 2
    },
    "receiveAmount": {
        "value": 14100,
        "currency": "USD",
        "decimals": 2
    },
    "referenceRate": 5.6425,
    "customerRate": 5.6538,
    "createdAt": "YYYY-MM-DDTHH:mm:SSs"
}

How to Create an Order

Required parameters:

Optional parameters:

curl --location 'https://faas.dev.tracefinance.io/exchange/api/orders' \
--header 'X-Trace-Version: 2' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer *****' \
--data '{
    "idempotentId": "idempotent-uuid",
    "counterpartyId": "counterparty-uuid",
    "currencyPair": {
        "source": "USDT",
        "target": "BRL"
    },
    "amount": {
        "value": "951000",
        "currency": "BRL"
    }
}'

Expected response:

{
    "id": "order-uuid",
    "idempotentId": "idempotent-uuid",
    "companyId": "company-uuid",
    "counterpartyId": "counterparty-uuid",
    "targetBankChannelId": null,
    "operation": "SELL",
    "currencyPair": {
        "source": "USDT",
        "target": "BRL"
    },
    "paymentAmount": {
        "value": 140577,
        "currency": "USDT",
        "decimals": 2
    },
    "receiveAmount": {
        "value": 791000,
        "currency": "BRL",
        "decimals": 2
    },
    "referenceRate": 5.6380,
    "customerRate": 5.6268,
    "currentState": {
        "status": "CREATED",
        "failReason": null,
        "atTime": "YYYY-MM-DDTHH:mm:SSs"
    },
    "states": [
        {
            "status": "CREATED",
            "failReason": null,
            "atTime": "YYYY-MM-DDTHH:mm:SSs"
        }
    ],
    "createdAt": "YYYY-MM-DDTHH:mm:SSs",

Listing Orders

Expected response for listing orders with pagination:

{
    "data": [
        {
            "id": "order-uuid",
            "idempotentId": "idempotent-uuid",
            "companyId": "company-uuid",
            "counterpartyId": "counterparty-uuid",
            "targetBankChannelId": null,
            "operation": "SELL",
            "currencyPair": {
                "source": "USDT",
                "target": "BRL"
            },
            "paymentAmount": {
                "value": 97246,
                "currency": "USDT",
                "decimals": 2
            },
            "receiveAmount": {
                "value": 547000,
                "currency": "BRL",
                "decimals": 2
            },
            "referenceRate": 5.6361,
            "customerRate": 5.6249,
            "currentState": {
                "status": "CREATED",
                "failReason": null,
                "atTime": "YYYY-MM-DDTHH:mm:SSs"
            },
            "states": [
                {
                    "status": "CREATED",
                    "failReason": null,
                    "atTime": "YYYY-MM-DDTHH:mm:SSs"
                }
            ],
            "createdAt": "YYYY-MM-DDTHH:mm:SSs",
            "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
        },
        {
            "id": "order-uuid",
            "idempotentId": "idempotent-uuid",
            "companyId": "company-uuid",
            "counterpartyId": "counterparty-uuid",
            "targetBankChannelId": "target-bank-channel-uuid",
            "operation": "BUY",
            "currencyPair": {
                "source": "BRL",
                "target": "USD"
            },
            "paymentAmount": {
                "value": 161000,
                "currency": "BRL",
                "decimals": 2
            },
            "receiveAmount": {
                "value": 27521,
                "currency": "USD",
                "decimals": 2
            },
            "referenceRate": 5.6407,
            "customerRate": 5.6520,
            "currentState": {
                "status": "PROCESSED",
                "failReason": null,
                "atTime": "YYYY-MM-DDTHH:mm:SSs"
            },
            "states": [
                {
                    "status": "CREATED",
                    "failReason": null,
                    "atTime": "YYYY-MM-DDTHH:mm:SSs"
                },
                {
                    "status": "PROCESSED",
                    "failReason": null,
                    "atTime": "YYYY-MM-DDTHH:mm:SSs"
                }
            ],
            "createdAt": "YYYY-MM-DDTHH:mm:SSs",
            "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
        }
    ],
    "meta": {
        "previousCursor": null,
        "nextCursor": "next-cursor",
        "total": 2,
        "totalMatches": null
    }
}

Common Errors

RESOURCE_NOT_FOUND

Invalid or non-existent ID.

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "ResourceName with id equal to uuid not found",
  "details": {
    "resource": "ResourceName",
    "field": "id",
    "value": "uuid"
  }
}

EXCEEDED_TRADING_LIMIT

Maximum number of operations for the period has been exceeded.

{
  "code": "EXCEEDED_TRADING_LIMIT",
  "message": "Trading limit exceeded for period",
  "details": {
    "period": "1PH",
    "amount": {
      "value": 1000,
      "decimals": 2,
      "currency": "BRL"
    }
  }
}

AMOUNT_CURRENCY_NOT_ALLOWED

Order currency not included in the currency pair.

{
  "code": "AMOUNT_CURRENCY_NOT_ALLOWED",
  "message": "The currency of amount must be one of currency pair",
  "details": {
    "currencyPair": {
      "source": "BRL",
      "target": "USD"
    }
  }
}

NON_POSITIVE_AMOUNT

Order amount must be positive.

{
  "code": "NON_POSITIVE_AMOUNT",
  "message": "Amount must be positive",
  "details": {
    "amount": {
      "value": 0,
      "decimals": 0,
      "currency": "BRL"
    }
  }
}

ORDER_UNSUPPORTED_TARGET_BANK_CHANNEL_TYPE

Bank account is incompatible with the order.

{
  "code": "ORDER_UNSUPPORTED_TARGET_BANK_CHANNEL_TYPE",
  "message": "Invalid bank channel type for this operation.",
  "details": {}
}

ORDER_UNSUPPORTED_TARGET_BANK_CHANNEL_OWNER

Order owner does not match the expected one.

{
  "code": "ORDER_UNSUPPORTED_TARGET_BANK_CHANNEL_OWNER",
  "message": "The specified owner of the bank channel is invalid.",
  "details": {
    "amount": {
      "value": 0,
      "decimals": 0,
      "currency": "BRL"
    }
  }
}

Updated 19 days ago