Guides
Dashboard

Couterparty

Available since API version 2

Suggest Edits

Table of Contents

What is a counterparty in foreign exchange operations?

In the context of foreign exchange operations, a counterparty represents a third party involved in the payment or receipt of funds on behalf of the company.
A counterparty can be an individual, a legal entity, or a structure associated with the company.

Types of counterparty

Counterparties can take on different roles depending on the type of transaction:

  • Buy (outbound): the counterparty acts as the beneficiary
  • Sell (inbound): the counterparty acts as the originator (who makes the payment)

➡️ Buy (Outbound)

The counterparty (beneficiary) will receive the converted funds in foreign currency or crypto asset through one of its registered banking channels.

⬅️ Sell (Inbound)

The counterparty (originator) will make the payment through a SWIFT or CRYPTO_WALLET channel, as indicated by Trace.
The amounts converted to BRL will be credited to a bank account of the company.

How to create a counterparty?

To register a new counterparty via the Trace Exchange API, send a POST request to the /counterparties endpoint with the required data.

curl --location 'https://faas.sandbox.tracefinance.io/exchange/api/counterparties' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_token_here>' \
--data '{
  "legalName": "Legal Name",
  "businessName": "Business Name",
  "taxId": null,
  "businessActivity": "Games",
  "address": {
    "country": "US",
    "address": "2860 Raver Croft Drive, Johnson City, Tennessee, 37601"
  },
  "webSites": [
    "http://www.example.com"
  ]
}'
  • The taxId can be null if not applicable at the moment of creation.
  • businessActivity must be a descriptive string representing the type of business (e.g., Games, Services, Finance).

All counterparties must be approved by Trace’s compliance team before they can be used in order creation.

Until approved, any attempt to associate them with an order will result in a validation error.

Counterparty statuses

⚠️

A counterparty can only be used to create orders when currentState.status is APPROVED.

Counterparty example

{
  "id": "counterparty-uuid",
  "companyId": "company-uuid",
  "name": "John Doe",
  "taxId": "12345678901234",
  "address": {
    "country": "US",
    "address": "2860 Raver Croft Drive, Johnson City, Tennessee, 37601"
  },
  "currentState": {
    "status": "APPROVED",
    "failReason": null,
    "atTime": "YYYY-MM-DDTHH:mm:SSs"
  },
  "states": [
    {
      "status": "CREATED",
      "failReason": null,
      "atTime": "YYYY-MM-DDTHH:mm:SSs"
    },
    {
      "status": "IN_REVIEW",
      "failReason": null,
      "atTime": "YYYY-MM-DDTHH:mm:SSs"
    },
    {
      "status": "APPROVED",
      "failReason": null,
      "atTime": "YYYY-MM-DDTHH:mm:SSs"
    }
  ],
  "createdAt": "YYYY-MM-DDTHH:mm:SSs",
  "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
}

How to list counterparties?

Listing all counterparties

Request

curl --location 'https://faas.dev.tracefinance.io/exchange/api/counterparties'

Response

{
  "data": [
    {
      "id": "counterparty-uuid",
      "companyId": "company-uuid",
      "name": "John Doe",
      "taxId": "12345678901234",
      "address": {
        "country": "US",
        "address": "2860 Raver Croft Drive, Johnson City, Tennessee, 37601"
      },
      "currentState": {
        "status": "APPROVED",
        "failReason": null,
        "atTime": "YYYY-MM-DDTHH:mm:SSs"
      },
      "states": [
        {
          "status": "CREATED",
          "failReason": null,
          "atTime": "YYYY-MM-DDTHH:mm:SSs"
        },
        {
          "status": "IN_REVIEW",
          "failReason": null,
          "atTime": "YYYY-MM-DDTHH:mm:SSs"
        },
        {
          "status": "APPROVED",
          "failReason": null,
          "atTime": "YYYY-MM-DDTHH:mm:SSs"
        }
      ],
      "createdAt": "YYYY-MM-DDTHH:mm:SSs",
      "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
    },
    {
      "id": "counterparty-uuid",
      "companyId": "company-uuid",
      "name": "Doe Joh",
      "taxId": "09876543210987",
      "address": {
        "country": "US",
        "address": "2860 Raver Croft Drive, Johnson City, Tennessee, 37601"
      },
      "currentState": {
        "status": "IN_REVIEW",
        "failReason": null,
        "atTime": "YYYY-MM-DDTHH:mm:SSs"
      },
      "states": [
        {
          "status": "CREATED",
          "failReason": null,
          "atTime": "YYYY-MM-DDTHH:mm:SSs"
        },
        {
          "status": "IN_REVIEW",
          "failReason": null,
          "atTime": "YYYY-MM-DDTHH:mm:SSs"
        }
      ],
      "createdAt": "YYYY-MM-DDTHH:mm:SSs",
      "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
    }
  ],
  "meta": {
    "previousCursor": null,
    "nextCursor": null,
    "total": 2,
    "totalMatches": null
  }
}

Listing approved counterparties

Request

curl --location 'https://faas.dev.tracefinance.io/exchange/api/counterparties?filters=currentState.status[last]=APPROVED'

Response

{
  "data": [
    {
      "id": "counterparty-uuid",
      "companyId": "company-uuid",
      "name": "John Doe",
      "taxId": "12345678901234",
      "address": {
          "country": "US",
          "address": "2860 Raver Croft Drive, Johnson City, Tennessee, 37601"
      },
      "currentState": {
          "status": "APPROVED",
          "failReason": null,
          "atTime": "YYYY-MM-DDTHH:mm:SSs"
      },
      "states": [
          {
              "status": "CREATED",
              "failReason": null,
              "atTime": "YYYY-MM-DDTHH:mm:SSs"
          },
          {
              "status": "IN_REVIEW",
              "failReason": null,
              "atTime": "YYYY-MM-DDTHH:mm:SSs"
          },
          {
              "status": "APPROVED",
              "failReason": null,
              "atTime": "YYYY-MM-DDTHH:mm:SSs"
          }
      ],
      "createdAt": "YYYY-MM-DDTHH:mm:SSs",
      "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
    }
  ],
  "meta": {
    "previousCursor": null,
    "nextCursor": null,
    "total": 1,
    "totalMatches": null
  }

Sandbox environment

How to Simulate a Rejected Counterparty?

To simulate the rejection of a counterparty in the sandbox environment, you just need to register it with an address in one of the countries listed below.

Country CodeCountry Name
KPKorea (Democratic People's Republic of)
LBLebanon
CUCuba
IRIran (Islamic Republic of)

Example Request

curl --location --globoff '{{exchange-service-url}}/api/counterparties' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "legalName": "Kim Jong-un",
  "businessName": "Supreme Leader",
  "taxId": null,
  "businessActivity": "Dictator",
  "address": {
    "value": "Residence No. 55 - Pyongyang",
    "country": "KP"
  },
  "webSites": [
    "https://overseas.mofa.go.kr"
  ]
}'

The sandbox environment runs a simulation routine every 10 minutes during business hours to review counterparties. Below is an example of a rejection result:

{
  "id": "counterparty-uuid",
  "companyId": "company-uuid",
  "legalName": "Kim Jong-un",
  "businessName": "Supreme Leader",
  "taxId": null,
  "businessActivity": "Dictator",
  "address": {
    "country": "KP",
    "address": "Residence No. 55 - Pyongyang"
  },
  "currentState": {
    "status": "REJECTED",
    "failReason": {
      "code": "COUNTRIES_WITH_TRADE_RESTRICTIONS",
      "message": "countries with trade restrictions",
      "details": {
        "countryCode": "KP"
      }
    },
    "atTime": "YYYY-MM-DDTHH:mm:SSs"
  },
  "webSites": [
    "https://overseas.mofa.go.kr"
  ],
  "states": [
    {
      "status": "CREATED",
      "failReason": null,
      "atTime": "YYYY-MM-DDTHH:mm:SSs"
    },
    {
      "status": "IN_REVIEW",
      "failReason": null,
      "atTime": "YYYY-MM-DDTHH:mm:SSs"
    },
    {
      "status": "REJECTED",
      "failReason": {
        "code": "COUNTRIES_WITH_TRADE_RESTRICTIONS",
        "message": "countries with trade restrictions",
        "details": {
          "countryCode": "KP"
        }
      },
      "atTime": "YYYY-MM-DDTHH:mm:SSs"
    }
  ],
  "createdAt": "YYYY-MM-DDTHH:mm:SSs",
  "updatedAt": "YYYY-MM-DDTHH:mm:SSs"
}

Updated 18 days ago