Midaz in a Global Portfolio

You can use Midaz as the ledger for a global account you wish to offer, similar to what major banks do (where the same client can have accounts in BRL 🇧🇷, USD 🇺🇸, EUR 🇪🇺, etc.). For this, assets need to be created using the Create an Instrument endpoint as shown below.

POST /v1/organizations/{{id}}/ledgers/{{id}}/instruments

Body:

{
  "name": "Brazilian Real",
  "type": "currency",
  "code": "BRL",
  "metadata": {
    "country": "Brazil"
  }
}

201:

{
  "id": "bb907427-5a8c-4622-b1ce-801b70e40d0c",
  "organizationId": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
  "name": "Brazilian Real",
  "type": "currency",
  "code": "BRL",
  "metadata": {
    "country": "Brazil"
  }
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "createdAt": "2024-02-08T17:03:12+0300",
  "updatedAt": "2024-02-08T17:03:12+0300",
  "deletedAt": null
}

After that, the portfolio for the client can be created. Think of the portfolio as a grouping of accounts, commonly referred to as a "wallet." Just like a real wallet, a portfolio can have accounts with different assets (instruments). To create the portfolio, the Create a Portfolio endpoint should be called.

POST /v1/organizations/{{id}}/ledgers/{{id}}/portfolios

Body:

{
  "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
  "name": "My portfolio",
  "status": {
    "code": "available",
    "description": null
  }
}

201:

{
  "id": "298c1e79-00b8-4f4b-a045-dd7300213b7a",
  "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
  "ledgetId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "My portfolio",
  "status": {
    "code": "available",
    "description": null
  },
  "metadata": null,
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

Use the entityId as the ID that identifies the client on your side. In the future, Midaz will provide the Entities Satellite to manage this for clients as well.

With the portfolio and instrument created, accounts can be created using the Create an Account endpoint as shown below.

POST /v1/organizations/{{id}}/ledgers/{{id}}/portfolios/{{id}}/accounts

Body:

{
  "instrumentCode": "BRL",
  "alias": "jhondoe_brl",
  "name": "My BRL account",
  "type": "deposit"
}

201:

{
  "id": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
  "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
  "ledgetId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "parentAccountId": null,
  "productId": null,
  "name": "My BRL account",
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "allowSending": true,
  "allowReceiving": true,
  "alias": "jhondoe_brl",
  "instrumentCode": "BRL",
  "type": "deposit",
  "balance": {
    "available": 0,
    "onHold": 0,
    "scale": 0
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}

Given that in this example accounts in BRL, USD, and EUR would be created, the POST /instruments and POST /accounts endpoints would be called three times.

Once this is done, when the Retrieve all Accounts endpoint is called for the specific portfolio, the three accounts will be returned as shown below.

GET /v1/organizations/{{id}}/ledgers/{{id}}/portfolios/{{id}}/accounts

200:

[
    {
      "id": "776c4fcd-62dc-4aaa-842c-6bbcbe35ed76",
      "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
      "ledgetId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
      "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
      "parentAccountId": null,
      "productId": null,
      "name": "My BRL account",
      "status": {
        "code": "ACTIVE",
        "description": null
      },
      "allowSending": true,
      "allowReceiving": true,
      "alias": "jhondoe_brl",
      "instrumentCode": "BRL",
      "type": "deposit",
      "balance": {
        "available": 0,
        "onHold": 0,
        "scale": 0
      },
      "createdAt": "2024-02-08T16:59:31+0300",
      "updatedAt": "2024-02-08T16:59:31+0300",
      "deletedAt": null
    },
    {
      "id": "812836cc-0d92-4435-a487-7c173a750206",
      "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
      "ledgetId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
      "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
      "parentAccountId": null,
      "productId": null,
      "name": "My USD account",
      "status": {
        "code": "ACTIVE",
        "description": null
      },
      "allowSending": true,
      "allowReceiving": true,
      "alias": "jhondoe_usd",
      "instrumentCode": "BRL",
      "type": "deposit",
      "balance": {
        "available": 0,
        "onHold": 0,
        "scale": 0
      },
      "createdAt": "2024-02-08T16:59:31+0300",
      "updatedAt": "2024-02-08T16:59:31+0300",
      "deletedAt": null
    },
    {
      "id": "46b97050-644c-4f7d-ad4a-2c607d0c6db0",
      "entityId": "1b8037e8-459d-4bf4-a1f9-0d075b500910",
      "ledgetId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
      "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
      "parentAccountId": null,
      "productId": null,
      "name": "My EUR account",
      "status": {
        "code": "ACTIVE",
        "description": null
      },
      "allowSending": true,
      "allowReceiving": true,
      "alias": "jhondoe",
      "instrumentCode": "BRL",
      "type": "deposit",
      "balance": {
        "available": 0,
        "onHold": 0,
        "scale": 0
      },
      "createdAt": "2024-02-08T16:59:31+0300",
      "updatedAt": "2024-02-08T16:59:31+0300",
      "deletedAt": null
    }
]