Couterparty
Available since API version 2
Table of Contents
- What is a counterparty in foreign exchange operations?
- Types of banking channels
- How to create a counterparty?
- How to list counterparties?
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 benull
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
isAPPROVED
.
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
}
Updated about 2 hours ago