Stablecoins

Stablecoins are digital assets pegged to the value of the US Dollar (USD) at a 1:1 ratio. Attrus supports stablecoin transactions, allowing you to convert local currencies into stablecoins, exchange between stablecoins, or move funds between stablecoins and fiat currencies — all using the same transaction endpoint you already use for traditional FX operations.

Supported stablecoins:

Stablecoin	Description
`USDT`	Tether USD — the most widely used stablecoin
`USDC`	USD Coin — issued by Circle
`USDG`	Global Dollar — a regulated stablecoin
`RLUSD`	Ripple USD — issued by Ripple

How Stablecoins Work

Stablecoin transactions use the same POST /transactions endpoint as all other Attrus operations. You specify the source currency in the currency field and the destination stablecoin (or vice versa) in the exchange_currency field.

Key concepts:

Stablecoin exchange rates are derived from the corresponding USD spot rate. For example, the BRL → USDT rate is the same as the BRL → USD rate
Exchanges between stablecoins (e.g., USDT → USDC) and between stablecoins and USD use a 1.0 spot rate. Attrus's FX margin is applied on top of this base rate
Exchanges between stablecoins and other fiat currencies (e.g., USDT → EUR) use the corresponding USD-based rate
Each stablecoin has its own internal bank accounts within Attrus (cash-in and cash-out), similar to fiat currency accounts
Stablecoin accounts are provided during onboarding and can be found in the Bank Accounts section of the Attrus Portal

Allowed Currency Pairs

Below is a summary of the allowed exchange directions for stablecoin transactions:

Direction	Example	Allowed
Local currency ↔ Stablecoin	BRL → USDT, USDT → BRL	Yes
Fiat currency ↔ Stablecoin	USD → USDT, USDT → EUR	Yes
Stablecoin ↔ Stablecoin	USDT → USDC, USDG → RLUSD	Yes

Pay-In: Local Currency to Stablecoin

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "subject_id": "customer id",
    "from_bank_account_id": "your physical BRL bank account id",
    "to_bank_account_id": "your internal USDT cash-in id",
    "currency": "BRL",
    "exchange_currency": "USDT",
    "value": "5000.00"
  }
}'

200OK

{
  "data": {
    "value": "5000.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "intermediary_bank_account": null,
      "id": "7a9c87a2-2d54-4f9e-83f7-4f4536ae58cc",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USDT",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "subject_is_receiver": false,
    "subject_id": "deb1a9eb-39d0-4d3d-ab30-bee5406d8e21",
    "status": "pending",
    "source_name": "John Doe",
    "source_document_type": "cpf",
    "source_document_number": "01234567890",
    "meta": null,
    "inserted_at": "2025-07-10T14:30:00.000000",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": {
        "type": "email",
        "key": "[email protected]"
      },
      "owner_name": "FACILITA PAGAMENTOS S/A",
      "owner_document_number": "10789035000105",
      "id": "97313a02-bbbb-4341-bb2c-3602d185d926",
      "iban": null,
      "currency": "BRL",
      "branch_number": "0001",
      "branch_country": "BRA",
      "bank": {
        "swift": "PLURBRRJ",
        "name": "Facilita Bank S.A.",
        "id": "292c1958-4926-4c7d-8550-6ce9c0952552",
        "code": "125"
      },
      "account_type": "conta-corrente",
      "account_number": "3467-3",
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "833.33",
    "exchange_under_request": false,
    "exchange_currency": "USDT",
    "estimated_value_until_exchange": false,
    "currency": "BRL",
    "cleared": true,
    "bank_transaction": null
  }
}

This example simulates a pay-in transaction where your customer pays 5,000 BRL via PIX or TED, and the funds are converted to USDT. The exchange rate used is the same as the BRL → USD rate, since USDT is pegged 1:1 to USD.

The same flow applies to all supported local currencies (MXN, COP, CLP) — just change the currency and from_bank_account_id to match the respective country.

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`transaction`	An object containing all the required values	object	true
`subject_id`	The ID of the registered customer	UUID	true
`from_bank_account_id`	The ID of your local currency bank account (e.g., BRL)	UUID	true
`to_bank_account_id`	The ID of your internal stablecoin cash-in account (e.g., USDT)	UUID	true
`currency`	Source currency — must be a local currency: BRL, MXN, COP or CLP	string	true
`exchange_currency`	Destination stablecoin: USDT, USDC, USDG or RLUSD	string	true
`value`	Amount in the source currency with two decimal places, e.g., "5000.00"	string	true

Conversion: Fiat Currency to Stablecoin

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "USD",
    "exchange_currency": "USDT",
    "value": "1000.00",
    "from_bank_account_id": "your internal USD cash-in id",
    "to_bank_account_id": "your internal USDT cash-in id",
    "subject_id": "your partner_id"
  }
}'

200OK

{
  "data": {
    "value": "1000.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "id": "7a9c87a2-2d54-4f9e-83f7-4f4536ae58cc",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USDT",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "status": "exchanged",
    "source_name": "Partner Company",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "meta": null,
    "inserted_at": "2025-07-10T15:00:00.000000",
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "id": "74416779-ad7b-4b7c-918e-21598700effd",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "1000.00",
    "exchange_under_request": false,
    "exchange_currency": "USDT",
    "estimated_value_until_exchange": false,
    "currency": "USD",
    "cleared": true,
    "bank_transaction": null
  }
}

Since stablecoins are pegged 1:1 to USD, the spot rate between USD and any stablecoin is 1.0. For other fiat currencies (e.g., EUR), the rate is derived from the corresponding USD rate. Attrus's FX margin (operational cost) is applied on top of the base rate, just like any other currency pair. You can use any supported fiat currency (USD, EUR, etc.) in the currency field.

Conversions are only allowed between accounts of the same flow type — cash-in to cash-in, or cash-out to cash-out.

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`transaction`	An object containing all the required values	object	true
`currency`	Source fiat currency (e.g., USD, EUR)	string	true
`exchange_currency`	Destination stablecoin: USDT, USDC, USDG or RLUSD	string	true
`value`	Amount in the source fiat currency with two decimal places, e.g., "1000.00"	string	true
`from_bank_account_id`	Your internal fiat currency account ID (must match the `currency` field)	UUID	true
`to_bank_account_id`	Your internal stablecoin cash-in account ID	UUID	true
`subject_id`	Your partner ID with Attrus	UUID	true

Conversion: Stablecoin to Stablecoin

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "USDT",
    "exchange_currency": "USDC",
    "value": "500.00",
    "from_bank_account_id": "your internal USDT cash-in id",
    "to_bank_account_id": "your internal USDC cash-in id",
    "subject_id": "your partner_id"
  }
}'

200OK

{
  "data": {
    "value": "500.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "id": "ecb55d58-8a84-4ef6-a63d-2ae6b8f6cb9a",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USDC",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "status": "exchanged",
    "source_name": "Partner Company",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "meta": null,
    "inserted_at": "2025-07-10T15:30:00.000000",
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "id": "7a9c87a2-2d54-4f9e-83f7-4f4536ae58cc",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USDT",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "500.00",
    "exchange_under_request": false,
    "exchange_currency": "USDC",
    "estimated_value_until_exchange": false,
    "currency": "USDT",
    "cleared": true,
    "bank_transaction": null
  }
}

All supported stablecoins share the same underlying USD-pegged value, so conversions between any combination of stablecoins use a 1.0 spot rate. Attrus's FX margin is applied on top of this base rate.

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`transaction`	An object containing all the required values	object	true
`currency`	Source stablecoin: USDT, USDC, USDG or RLUSD	string	true
`exchange_currency`	Destination stablecoin: USDT, USDC, USDG or RLUSD	string	true
`value`	Amount with two decimal places, e.g., "500.00"	string	true
`from_bank_account_id`	Your internal source stablecoin account ID	UUID	true
`to_bank_account_id`	Your internal destination stablecoin account ID	UUID	true
`subject_id`	Your partner ID with Attrus	UUID	true

Conversion: Stablecoin to Fiat Currency

curl -X POST "https://api.facilitapay.com/api/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...." \
  -d '{
  "transaction": {
    "currency": "USDT",
    "exchange_currency": "USD",
    "value": "2000.00",
    "from_bank_account_id": "your internal USDT cash-in id",
    "to_bank_account_id": "your internal USD cash-in id",
    "subject_id": "your partner_id"
  }
}'

200OK

{
  "data": {
    "value": "2000.00",
    "to_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "id": "74416779-ad7b-4b7c-918e-21598700effd",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USD",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "subject_is_receiver": true,
    "subject_id": "d6db1129-0ed3-4da7-9beb-d8c6326465f2",
    "status": "exchanged",
    "source_name": "Partner Company",
    "source_document_type": "cpf",
    "source_document_number": "21958642819",
    "meta": null,
    "inserted_at": "2025-07-10T16:00:00.000000",
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "from_credit_card": null,
    "from_bank_account": {
      "routing_number": null,
      "pix_info": null,
      "owner_name": "Partner Company Ltd.",
      "owner_document_number": "21958642819",
      "internal": true,
      "id": "7a9c87a2-2d54-4f9e-83f7-4f4536ae58cc",
      "iban": null,
      "flow_type": "cash_in",
      "currency": "USDT",
      "branch_number": null,
      "branch_country": null,
      "bank": {
        "swift": null,
        "name": "Internal",
        "id": "6facab8d-573e-44d0-a4bd-ce2600368263",
        "code": "999"
      },
      "account_type": "conta-corrente",
      "account_number": null,
      "aba": null
    },
    "for_exchange": true,
    "exchanged_value": "2000.00",
    "exchange_under_request": false,
    "exchange_currency": "USD",
    "estimated_value_until_exchange": false,
    "currency": "USDT",
    "cleared": true,
    "bank_transaction": null
  }
}

Converting from a stablecoin to a fiat currency uses the corresponding exchange rate (e.g., 1.0 for USD, or the USD-derived rate for EUR and other currencies), with Attrus's FX margin applied. This is useful when you want to consolidate stablecoin holdings into fiat currency before settling to your international bank account.

HTTP Request

POST /transactions

Body Parameters

Parameter	Description	Type	Required
`transaction`	An object containing all the required values	object	true
`currency`	Source stablecoin: USDT, USDC, USDG or RLUSD	string	true
`exchange_currency`	Destination fiat currency (e.g., USD, EUR)	string	true
`value`	Amount with two decimal places, e.g., "2000.00"	string	true
`from_bank_account_id`	Your internal stablecoin account ID	UUID	true
`to_bank_account_id`	Your fiat currency account ID (must match the `exchange_currency` field)	UUID	true
`subject_id`	Your partner ID with Attrus	UUID	true

Exchange Rates for Stablecoins

The exchange rates endpoint (GET /exchange_rates) also returns rates for stablecoin pairs. Stablecoin rates follow these rules:

For local currency → stablecoin pairs:

The rate is the same as the corresponding local currency → USD rate. For example, brlusdt and brlusd will return the same value, since USDT is pegged 1:1 to USD. The same applies to brlusdc, brlusdg, and brlusdrlusd.

For stablecoin ↔ USD and stablecoin ↔ stablecoin pairs:

The spot rate is always 1.0, reflecting the 1:1 peg. For example: usdtusdcspot, usdtusdspot, usdcusdgspot — all return 1.0. The final rates returned by the endpoint already include Attrus's FX margin (operational cost) applied on top of the spot rate.

For stablecoin ↔ other fiat currency pairs (EUR, GBP, etc.):

The rate is derived from the corresponding USD rate. For example, the USDT → EUR rate will match the USD → EUR rate, since the stablecoin is pegged to USD.

Tax Treatment

Exchanges between fiat currencies and stablecoins, or between different stablecoins, are treated as withdrawal operations for tax purposes (IOF calculation). This means the IOF rate applied to these transactions follows the withdrawal IOF rate rather than the standard FX IOF rate.

Business Rules Summary

Important requirements:

Stablecoin transactions use the same POST /transactions endpoint as all other Attrus transactions
You must have stablecoin internal bank accounts set up during onboarding — check the Bank Accounts section of the Attrus Portal
from_bank_account_id is not required for stablecoin or foreign currency transactions — the system will automatically select the appropriate source account when applicable
Conversions between internal accounts are only allowed between accounts of the same flow type: cash-in to cash-in, or cash-out to cash-out
Attrus's FX margin (operational cost) applies to all stablecoin transactions, including stablecoin-to-stablecoin and stablecoin-to-fiat conversions

warning

Common Mistakes

{
  "errors": {
    "from_bank_account_id": [
      "account currency does not match transaction currency"
    ]
  }
}

How Stablecoins Work​

Allowed Currency Pairs​

Pay-In: Local Currency to Stablecoin​

HTTP Request​

Body Parameters​

Conversion: Fiat Currency to Stablecoin​

HTTP Request​

Body Parameters​

Conversion: Stablecoin to Stablecoin​

HTTP Request​

Body Parameters​

Conversion: Stablecoin to Fiat Currency​

HTTP Request​

Body Parameters​

Exchange Rates for Stablecoins​

Tax Treatment​

Business Rules Summary​

How Stablecoins Work

Allowed Currency Pairs

Pay-In: Local Currency to Stablecoin

HTTP Request

Body Parameters

Conversion: Fiat Currency to Stablecoin

HTTP Request

Body Parameters

Conversion: Stablecoin to Stablecoin

HTTP Request

Body Parameters

Conversion: Stablecoin to Fiat Currency

HTTP Request

Body Parameters

Exchange Rates for Stablecoins

Tax Treatment

Business Rules Summary