Open multi-currency account

Step-by-step guide to opening an account that holds one or more currencies for an account owner.

Overview

An account in Trace FX is multi-currency: every account includes crypto support by default, and you declare which fiat assets (like BRL) to enable when you create it. Each fiat asset and the crypto wallet run their own onboarding pipelines.

Prerequisites

• Valid authentication credentials.
• Account owner details (company legal name, tax ID, industry, and address).

Steps

1. Create the account

   Submit a request with the fiat assets to enable and the account owner’s details. Crypto support is always included — you don’t need to declare it.

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/accounts \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --header 'Content-Type: application/json' \
     --data '{
       "assets": [
         { "code": "BRL", "isVirtual": false }
       ],
       "owner": {
         "type": "COMPANY",
         "legalName": "Acme Ltda",
         "taxId": {
           "value": "11222333000181",
           "type": "CNPJ",
           "country": "BR"
         },
         "industry": "INFORMATION_TECHNOLOGY",
         "incorporateDate": "2018-05-12",
         "address": {
           "addressLine1": "Rua das Flores, 100",
           "addressLine2": "Suite 456",
           "city": "São Paulo",
           "state": "SP",
           "country": "BR",
           "postalCode": "01234-567"
         }
       }
     }'
   

   The response returns the account in ACTION_REQUIRED status along with the document types required for onboarding under requirements.currentlyDue. Fiat onboarding requires document uploads; crypto has none.

2. Upload required documents

   The creation response includes a requirements.currentlyDue array listing every document you need to provide. Each item carries a documentType (and, for grouped requirements, an options array of acceptable types). Documents are uploaded against the flat /api/documents endpoint — set holder.type to ACCOUNT and holder.referenceId to the account ID:

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/documents \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --form 'body={"documentType":"ARTICLES_OF_ASSOCIATION","holder":{"type":"ACCOUNT","referenceId":"<account-id>"}};type=application/json' \
     --form 'file=@/path/to/articles-of-association.pdf'
   

   Returns 204 No Content. Upload one document per request, repeating for every requirement listed in currentlyDue.

3. Add beneficial owners (company accounts)

   Company-owned accounts require at least one beneficial owner (UBO). Register each UBO with their identity and address details:

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/accounts/<account-id>/ubos \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "João Silva",
       "taxId": {
         "value": "12345678909",
         "type": "CPF",
         "country": "BR"
       },
       "address": {
         "addressLine1": "Rua das Flores, 100",
         "city": "São Paulo",
         "state": "SP",
         "country": "BR",
         "postalCode": "01234-567"
       },
       "ownershipPercentage": 50.0
     }'
   

   The response includes the UBO’s id, which you’ll need for uploading their documents.

4. Upload UBO documents

   Each UBO needs identity documents. Use the same /api/documents endpoint — set holder.type to UBO and holder.referenceId to the UBO’s id. Identity documents typically require a documentSubType (e.g., FRONT_SIDE / BACK_SIDE) and a metadata.country:

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/documents \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>' \
     --form 'body={"documentType":"ID_CARD","documentSubType":"FRONT_SIDE","holder":{"type":"UBO","referenceId":"<ubo-id>"},"metadata":{"country":"BR"}};type=application/json' \
     --form 'file=@/path/to/ubo-id-front.pdf'
   

   Returns 204 No Content. Repeat for every side and every UBO registered on the account.

5. Submit for review

   Once all required documents are uploaded, submit the account for compliance review. This endpoint has no request body:

   curl --request POST \
     --url https://api.sandbox.tracefinance.com/api/accounts/<account-id>/review \
     --header 'Authorization: Bearer <token>' \
     --header 'X-Idempotency-Key: <unique-key>'
   

   Returns 202 Accepted. The account transitions from ACTION_REQUIRED to REVIEWING. If any documents are still missing or rejected, the API returns 422 with a MISSING_DOCUMENTS_FOR_REVIEW error listing the outstanding documentType names.

6. Wait for activation

   After review is approved, each asset activates on its own pipeline. Poll GET /api/accounts/{accountId} — the account moves through OPENING and becomes ACTIVE once the first underlying provider account finishes onboarding (typically the crypto wallet, since it has no manual steps). Each entry in the response’s assets array carries its own provider-account status (ONBOARDING, ACTIVE, FAILED, FROZEN, DEACTIVATED) so you can see which assets are ready.

7. Retrieve funding instructions

   Once the account is active, retrieve the incoming transfer details for each active asset:

   curl --request GET \
     --url https://api.sandbox.tracefinance.com/api/accounts/<account-id>/fundingInstructions \
     --header 'Authorization: Bearer <token>'
   

   Response

   [
     {
       "asset": "BRL",
       "rail": "PIX",
       "type": "PIX_KEY",
       "keyType": "CNPJ",
       "key": "12345678000101"
     }
   ]
   

What happens next

• Make a deposit — fund the account with BRL or crypto.
• Execute a swap — convert between the account’s assets.