Skip to main content

​
Overview

An account in Trace Finance 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 (legal name, tax ID, industry, expected monthly volume, and address). See KYC/KYB for the document checklist that follows account creation.

​
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" }
    ],
    "owner": {
      "type": "COMPANY",
      "legalName": "Acme Ltda",
      "taxId": {
        "value": "11222333000181",
        "type": "CNPJ"
      },
      "industry": "SOFTWARE_DEVELOPMENT",
      "expectedMonthlyVolume": "FROM_0_TO_50000",
      "incorporateDate": "2018-05-12",
      "isStartup": false,
      "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. Need to fix a rejected field after creation? Use PATCH /api/accounts/{accountId} to replace the owner profile before submitting for review.
2

Upload required documents

The creation response includes a requirements.currentlyDue array listing every document you need to provide. Each item carries a type discriminator — ACCOUNT_DOCUMENT / UBO_DOCUMENT for a specific documentType, or IDENTITY_VERIFICATION / INCORPORATION_DOCUMENT for a grouped requirement whose options array lists the acceptable document types together with the subTypes and requiredMetadata each option needs. 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, contact, and address details. phone and email are required so we can reach the UBO for follow-up during compliance review.
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"
    },
    "address": {
      "addressLine1": "Rua das Flores, 100",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postalCode": "01234-567"
    },
    "phone": "5511999999999",
    "email": "joao.silva@example.com",
    "ownershipPercentage": 50.0,
    "isLegalRepresentative": false
  }'
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. Subscribe to the ACCOUNT_ASSET_ACTIVATED and ACCOUNT_ASSET_FAILED webhooks to react as each asset finishes, or 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",
    "type": "PIX_KEY",
    "rail": "PIX_KEY",
    "keyType": "CNPJ",
    "key": "12345678000101",
    "accountIdentifier": null
  }
]
Filter the catalog with the optional asset and rail query parameters when you only need one rail for an asset.

​
What happens next