Transaction
Transactions are the base input used by Gorila's engine to generate all the metrics of a portfolio.
They reflect real-life transactions that are executed at brokerage houses or exchanges. Most transactions can be created using the pool of securities that Gorila manages an udpated.
There are cases when you'll need to create a security using our models for fixed income. Also, we allow the possibility to create Custom Securities, which are securities made up and updated by the API user. All created securities will be scoped at the API's user Organization level. Meaning they'll only appear to API Keys from your organization.
We separate Transactions in five major types: REGULAR, COME_COTAS, OPTION_EXERCISE, CUSTODY_TRANSFER and SUBSCRIPTION_RECEIPT_EXERCISE.
Regular
These are the most common types of transactions and is the most important type to understand. We've separated Regular transactions into four variants that are related to the basic information needed to register them (click for examples):
The idea behind these variations is to narrow the necessary fields and return a corresponding error message to help you avoid unintended input mistakes.
Regular-type transactions encompasses the following security types (click to see an example):
Price and Quantity
- Banking Bonds (CDB, LC, LCA, LCI, LF):
CORPORATE_BONDS_CDB,CORPORATE_BONDS_LC,CORPORATE_BONDS_LCA,CORPORATE_BONDS_LCI,CORPORATE_BONDS_LF - BDR:
STOCK_BDR - COE:
STRUCTURED_COE - Commodities:
CURRENCY_COMMODITY - Corporate Bonds (CRA, CRI, Debentures):
CORPORATE_BONDS_CRA,CORPORATE_BONDS_CRI,CORPORATE_BONDS_DEBENTURE - Cryptocurrencies:
CRYPTOCURRENCY - ETF:
STOCK_ETF - FII:
FII - Funds:
FUNDQUOTE - Futures:
FUTURES - Custom Securities:
GENERIC - Government Bonds:
TREASURY_LOCAL_LFT,TREASURY_LOCAL_LTN,TREASURY_LOCAL_NTNBP,TREASURY_LOCAL_NTNB,TREASURY_LOCAL_NTNB1,TREASURY_LOCAL_NTNC,TREASURY_LOCAL_NTNF - Index Options:
OPTION_INDEX - Stock Forwards:
FORWARD_STOCK - Stock Indexes:
STOCK_INDEX - Stock Options:
OPTION_LOCAL - Stock Receipts:
STOCK_RECEIPT - Stock Rights:
STOCK_RIGHTS - Stocks:
STOCK_LOCAL
Quantity-only Securities
Price, Exchange Rate and Quantity Securities
Exchange Rate and Quantity Securities
Come Cotas
For some Brazilian funds, there's a special taxation called "Come Cotas". The tax works as an advance payment of the Withholding Income Tax and takes place twice a year, on the last working day of May and November.
Come-cotas is an unusual tax since it taxes the quantity of fund shares of the holder. To find out how payment works, visit our blog: Come-cotas: como é a tributação sobre os fundos de investimento.
Since there are some discrepancies in how custodians apply the tax, you need to create a transaction on top of an existing security in your portfolio that states the quantity to be subtracted from the position.
Example: Come Cotas: COME_COTAS
Options Exercise
An options exercise means to put into effect the right to buy or sell the underlying financial instrument specified in an options contract. Suppose the owner of an option decides to buy or sell the underlying instrument instead of allowing the contract to expire worthlessly or closing out the position. In that case, they will be "exercising the option" or making use of the right or privilege that is available in the contract. An options holder may exercise their right to buy or sell the contract's underlying shares at a specified price, also called the strike price.
-
Exercising a put option allows you to sell the underlying security at a stated price within a specific timeframe.
-
Exercising a call option allows you to buy the underlying security at a stated price within a specific timeframe.
To learn more about options, visit our blog: O que são opções e como investir neste mercado?.
Example: Options Exercise: OPTION_EXERCISE
Custody Transfer
Consists of the procedure of changing the institution in charge of registering and safeguarding your investments (custodian). This happens when you switch brokerage firms or switch from a bank to a brokerage firm or vice-versa. In this way, the investor is able to change the institution responsible for a position or an entire portfolio without the need to redeem all the investments made.
Example: Custody Transfer: CUSTODY_TRANSFER
Stock Receipt Exercise
⚠️ Not implemented. Coming soon.
A subscription receipt for shares is a document that proves an investor's right to acquire shares of a company at a price below the market value. It contains information such as the company name, the number of shares the investor is entitled to purchase, the subscription price, the expiry date, and the conditions associated with the subscription.
The exercise of the receipt occurs when the holder decides to purchase the shares at the subscription price specified in the receipt. In Gorila, as it depends on a choice to be exercised, inserting the subscription receipt operation is necessary. On the expiration date of the receipt, it'll automatically be converted into the security in question.