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:

Status	Description	Webhook Triggered?
`CREATED`	Order created, awaiting processing	✅
`PROCESSED`	Order associated with a settlement	✅
`CANCELLED`	Order canceled	✅
`COMPLETED`	Payment 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:

counterpartyId (see: Counterparties)
currencyPair (see: Currency Pair)
amount

Optional parameter:

quoteId (see: Quote)

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:

idempotentId (see: Idempotency)
counterpartyId (see: Counterparties)
currencyPair (see: Currency Pair)
amount

Optional parameters:

quoteId (see: Quote)
targetBankChannelId (see: Bank Channels)

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