Security

All securities available in Gorila, which can be priced and added to a portfolio, are called Securities.

Most of them are available to be added to someone's portfolio using transactions (Transactions), while some must first be created in the organization's scope before they can be used.

Each security has a unique identifier (securityId), but, depending on its type, you can identify a security by other well-known identifiers used by financial market participants, such as the ISIN for most exchange-listed securities or the CNPJ for Brazilian funds. To find a security, use the List Securities endpoint, which lets you search by name or identifier and filter by type, class or classification.

Security types

Security types (type) are groupings that separate securities by similarities in terms of their nature, type of calculation and the information needed to express a transaction (transaction). It is a grouping similar to (but more granular than) an asset class. To group securities by classes and subclasses, see Security Classification.

Here are the security types (click the link to see an example of a transaction with each of them):

Security types managed by Gorila

Security types that need to be created

Security classification

Besides its type, each security fits into a tree of classes and subclasses with up to 4 levels, from CLASSIFICATION_L0 (the broadest, such as Fixed Income or Variable Income) to CLASSIFICATION_L3 (the most detailed). For example, an inflation-indexed government bond is under "Fixed Income > Inflation Indexed > Government Bond". This classification shows up in the classifications field of the security's data and is the basis for allocation analyses by class, for filters and groupings by classification (securityClassification and groupBy) and for Investment Profiles.

By default, securities follow Gorila's official classification. If your institution's logic is different, your organization can create custom classes and reclassify any security by providing the desired classificationId when updating the security (or null, to return it to the official classification). The reclassification applies to all of your organization's portfolios.

To understand the levels, how to create custom classes and the reclassification rules, see the Security Classification documentation.

Creating securities

Let's explore the cases for creating securities, their motivation and a practical example for each one. All of them use the Create Security endpoint, and the type field defines which security model is being created.

Banking Bonds (CDB, LC, LCA, LCI, LF and similar)

For some banking bonds there is no organized secondary market. The lack of this market, or even of an organized over-the-counter market, creates some difficulties for pricing purposes, such as the lack of a price provider, the lack of a public and unique identifier for each bond and the absence of a generally accepted mark-to-market pricing source.

These bonds can be fixed-rate (FIXED_RATE_BANKING_BOND) or floating-rate linked to an index (FLOATING_RATE_BANKING_BOND), and their types and rates vary according to each deal.

For these reasons, you first need to create the bond before creating transactions that refer to it. The bankingBondType field defines the bond type and, consequently, the resulting security type (type):

`bankingBondType`	Bond	Security type
`CDB`	Certificado de Depósito Bancário	`CORPORATE_BONDS_CDB`
`DPGE`	Depósito a Prazo com Garantia Especial	`CORPORATE_BONDS_DPGE`
`LC`	Letra de Câmbio	`CORPORATE_BONDS_LC`
`LCA`	Letra de Crédito do Agronegócio	`CORPORATE_BONDS_LCA`
`LCD`	Letra de Crédito do Desenvolvimento	`CORPORATE_BONDS_LCD`
`LCI`	Letra de Crédito Imobiliário	`CORPORATE_BONDS_LCI`
`LF`	Letra Financeira	`CORPORATE_BONDS_LF`
`LFS` and `LFSN`	Subordinated Letras Financeiras	`CORPORATE_BONDS_LFS` and `CORPORATE_BONDS_LFSN`
`LIG`	Letra Imobiliária Garantida	`CORPORATE_BONDS_LIG`
`RDB`	Recibo de Depósito Bancário	`CORPORATE_BONDS_RDB`
`RDC`	Recibo de Depósito Cooperativo	`CORPORATE_BONDS_RDC`
`P2B_LENDING`	P2B (peer-to-business) lending	`P2B_LENDING`
`REPO`	Repurchase agreement (Operação Compromissada)	`REPO`

The fields common to both models are:

bankingBondType, initialDate (issuance date), maturityDate and issuerId (issuer's CNPJ, unformatted): required.
issuanceFaceValue: face value at issuance. It is optional, but recommended.
interestPaymentPeriod: interest (coupon) payment frequency. Don't forget to provide this parameter for bonds that make periodic payments. Accepted values:
- BULLET (default, no intermediate payments), MONTHLY, EVERY_2_MONTHS, EVERY_3_MONTHS, EVERY_4_MONTHS, EVERY_6_MONTHS or YEARLY.

Integrating banking bonds

For a complete walkthrough, from registering the bond to checking the portfolio, and for the most common challenges of industry data (face value on a different scale, rates in different formats, secondary market purchases and custody transfers), see the Integrating banking bonds use case.

Below are two examples (one for a fixed-rate bond and another for a floating-rate bond) of the payloads we need to model the bonds:

Fixed-rate CDB example - Type: `FIXED_RATE_BANKING_BOND`

In the fixed-rate model, the annual rate is provided in decimal format in the yield field (e.g., 0.05 = 5% p.a.).

//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "FIXED_RATE_BANKING_BOND",
  "bankingBondType": "CDB",
  "initialDate": "2020-01-01",
  "maturityDate": "2040-12-31",
  "issuerId": "03215790000110",
  "issuanceFaceValue": 1000,
  "yield": 0.05
}

The response will return the Id (securityId) of the newly created security:

//RESPONSE

{
  "id": 44789070
}

With the securityId in hand, you can create a transaction with this security:

//REQUEST
//POST https://core.gorila.com.br/portfolios/{portfolioId}/transactions

{
  "type": "REGULAR",
  "transactDate": "2020-01-01",
  "quantity": 25,
  "price": 1000,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789070
  },
  "side": "BUY"
}

Floating-rate CDB example - Type: `FLOATING_RATE_BANKING_BOND`

In the floating-rate model, the index field defines the index (CDI, IPCA, IGPM or SELIC).

//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "FLOATING_RATE_BANKING_BOND",
  "bankingBondType": "CDB",
  "initialDate": "2020-01-01",
  "maturityDate": "2040-12-31",
  "issuerId": "03215790000110",
  "issuanceFaceValue": 100,
  "index": "CDI",
  "multiplier": 1.25
}

Note: the multiplier field is used only when the bond's return is a percentage (%) of an index (example: 120% of CDI → 1.20). For securities with hybrid returns, such as IPCA+ or CDI+, the field to use is spread (example: IPCA + 5% → 0.05). Send only one of the two.

The response will return the Id (securityId) of the newly created security:

//RESPONSE

{
  "id": 44789069
}

With the securityId in hand, you can create a transaction with this security:

//REQUEST
//POST https://core.gorila.com.br/portfolios/{portfolioId}/transactions

{
  "type": "REGULAR",
  "transactDate": "2022-04-15",
  "quantity": 30,
  "price": 103.4323,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789069
  },
  "side": "BUY"
}

Step-up CDB (progressive rate)

Some floating-rate bonds have a progressive rate: the percentage of the index changes on predefined dates (for example, it starts at 100% of CDI and goes up 5 percentage points every year). This kind of structure is modeled with the scaleType and scaling fields:

scaleType = INCREMENTAL: the new rate applies only from the change date onward. The bond's life is split into intervals, and the rate in effect is applied in each interval.
scaleType = RETROACTIVE: when the change date is reached, the new rate applies from the bond's start, causing a sharp change in price to reflect the bond's price as if it had earned more since the initialDate.

The multiplier still indicates the initial rate (the one in effect at issuance), and scaling lists only the subsequent changes, with the date and the new multiplier of each one. Both fields must be sent together and, currently, step-up rates are only accepted for bonds indexed to CDI, without spread and with interestPaymentPeriod equal to BULLET.

//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "FLOATING_RATE_BANKING_BOND",
  "bankingBondType": "CDB",
  "initialDate": "2025-01-01",
  "maturityDate": "2030-01-01",
  "issuerId": "30306294000145",
  "issuanceFaceValue": 1000,
  "index": "CDI",
  "multiplier": 1.0,
  "scaleType": "INCREMENTAL",
  "scaling": [
    { "date": "2026-01-01", "multiplier": 1.05 },
    { "date": "2027-01-01", "multiplier": 1.10 },
    { "date": "2028-01-01", "multiplier": 1.15 },
    { "date": "2029-01-01", "multiplier": 1.20 }
  ]
}

Stock Forwards (FORWARD_STOCK)

Stock forward contracts are customized contracts between two counterparties who agree to buy or sell a stock at a specified price on a future date (which is also the contract's maturity date). Since forward contracts are traded over the counter and can be customized between the parties, you will need to create them before registering a transaction.

To create stock forward contracts, you will need to specify the following information:

The underlying stock, represented by its securityId
The initial date (similar to an issuance date)
The maturity date

Stock forward example - Type: `FORWARD_STOCK`

//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "FORWARD_STOCK",
  "underlyingSecurity": {
    "id": 4855044
    // you can also use ISIN: "BRPETRACNPR6"
  },
  "initialDate": "2023-01-01",
  "maturityDate": "2023-12-31"
}

The response will return the Id (securityId) of the newly created security:

//RESPONSE

{
  "id": 44789071
}

With the securityId in hand, you can create a transaction with this security:

//REQUEST
//POST https://core.gorila.com.br/portfolios/{portfolioId}/transactions

{
  "type": "REGULAR",
  "transactDate": "2023-02-01",
  "quantity": 100,
  "brokerId": "58160789000128",
  "security": {
    "id": 44789071
  },
  "side": "BUY",
  "price": 25
}

Investment Clubs and Managed Funds

Investment clubs (INVESTMENT_CLUB) and managed funds (MANAGED_FUND) also need to be created before receiving transactions. Registration requires a name (name), description (description), asset class (assetClass) and initial date (initialDate), and optionally accepts the cnpj.

//REQUEST
//POST https://core.gorila.com.br/securities

{
  "type": "INVESTMENT_CLUB",
  "name": "Gorila Investment Club",
  "description": "Club made up of a diversified portfolio of equities and fixed income",
  "assetClass": "STOCKS",
  "initialDate": "2022-04-04"
}

As with custom securities, the quota value of these securities is provided by the organization through the Upsert Security Prices endpoint.

Custom Securities (GENERIC)

To learn more about creating and managing custom securities, click here.

Security types​

Security types managed by Gorila​

Security types that need to be created​

Security classification​

Creating securities​

Banking Bonds (CDB, LC, LCA, LCI, LF and similar)​

Fixed-rate CDB example - Type: FIXED_RATE_BANKING_BOND​

Floating-rate CDB example - Type: FLOATING_RATE_BANKING_BOND​

Step-up CDB (progressive rate)​

Stock Forwards (FORWARD_STOCK)​

Stock forward example - Type: FORWARD_STOCK​

Investment Clubs and Managed Funds​

Custom Securities (GENERIC)​

Security types

Security types managed by Gorila

Security types that need to be created

Security classification

Creating securities

Banking Bonds (CDB, LC, LCA, LCI, LF and similar)

Fixed-rate CDB example - Type: `FIXED_RATE_BANKING_BOND`

Floating-rate CDB example - Type: `FLOATING_RATE_BANKING_BOND`

Step-up CDB (progressive rate)

Stock Forwards (FORWARD_STOCK)

Stock forward example - Type: `FORWARD_STOCK`

Investment Clubs and Managed Funds

Custom Securities (GENERIC)