Skip to main content

Transaction

Transactions (transactions) are the input used by Gorila's engine to generate all the metrics of a portfolio.

They reflect real-life transactions that are executed at brokers or exchanges. Most transactions can be created using the pool of securities that Gorila manages and keeps up to date. However, there are cases (involving banking bonds) in which you will need to create the security (security) using our fixed income models. Security creation also applies to stock forwards.

In addition, we allow you to create generic securities (Custom Securities), which are securities created and updated by the API user. All created securities will be linked to the API user's organization level (Organization), meaning they will only be visible to your organization's API keys (API Keys).

The transaction types that can be created are: REGULAR, COME_COTAS, OPTION_EXERCISE, CUSTODY_TRANSFER, INITIAL_CUSTODY_ADJUSTMENT and POSITION_CLOSE. To create a transaction, use the Create Transaction endpoint.

Transaction status​

All transactions have a status field that indicates the current processing state of the transaction. This field is set to PROCESSING right after insertion, signaling that the transaction is in the calculation and validation phase. During this stage, all calculations and checks related to the transaction are performed to ensure that it is correctly reflected in the portfolio. Once all calculations and checks are successfully completed, the transaction status changes to COMPLETED, indicating that the transaction has been fully processed and integrated into the portfolio. This same status update process also takes place when the transaction is edited, in which case the status goes back to PROCESSING until all changes are properly processed and validated.

Avoiding duplicate transactions (idempotency key)​

The Create Transaction endpoint accepts the optional idempotency-key header: a unique identifier for the transaction, generated by your system (for example, a UUID or the operation's code in your database). It prevents the same transaction from being created twice when a request is repeated, for example, in a retry after a network failure or a timeout, when you do not know whether the first attempt was processed.

  • The key is unique per portfolio: two transactions in the same portfolio cannot have the same key. The same key can be used in different portfolios.
  • If the request is sent with a key already used in the portfolio, the transaction is not created and the API responds with an HTTP 409 Conflict error. The response includes the transactionId of the existing transaction, which you can query to confirm that it was recorded.
  • Without the header, each request creates a new transaction, even if the data is identical.
// REQUEST
// POST https://core.gorila.com.br/portfolios/{portfolioId}/transactions
// idempotency-key: 7d1f5c2e-3a9b-4e8f-b6d0-91c4a2e5f803

{
  "type": "REGULAR",
  "transactDate": "2023-03-07",
  "quantity": 500,
  "brokerId": "18945670000146",
  "security": {
    "isin": "BRMXRFCTF008"
  },
  "side": "BUY",
  "price": 9.50
}

If the same request is sent again with the same key, the response will be:

//RESPONSE 409

{
  "code": 409,
  "message": "idempotency key already used",
  "transactionId": "776287ce-4b50-4b7e-8e5b-23711578d4df"
}

Regular​

These are the most common types of transactions and, therefore, deserve full attention. We split Regular transactions (Regular) into four variants that are related to the basic information needed to register them (click to see examples):

The idea behind these variants is to simplify the fields needed to create the transaction and to return a corresponding error message to help avoid unintentional input mistakes.

Regular transactions cover the following security types (type). Click to see an example of how to create a transaction of each type:

Price and Quantity​

Quantity Only​

Price, Exchange Rate and Quantity​

Exchange Rate and Quantity​

Come Cotas​

For some Brazilian funds, there is 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 business day of May and November.

Come-cotas is an unusual tax, since it taxes the quantity of fund shares held by the investor. To understand how the payment works, visit our blog: Come-cotas: como é a tributação sobre os fundos de investimento.

Due to some discrepancies in the way brokers apply the tax, you need to create a COME_COTAS 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​

Options exercise means putting into practice 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 letting the contract expire worthless or closing out the position. In that case, they will be "exercising the option", or making use of the right or privilege available in the contract. To do so, you need to create an OPTION_EXERCISE transaction. 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 period.
  • Exercising a call option allows you to buy the underlying security at a stated price within a specific period.

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​

The CUSTODY_TRANSFER transaction should be used to reflect the procedure of changing the institution responsible for registering and safeguarding your investments (broker). This happens when you move an investment to another broker or migrate from a bank to a broker, or vice versa. This way, the investor can change the institution responsible for a position or for an entire portfolio without having to redeem all the investments made.

Example: Custody Transfer: CUSTODY_TRANSFER

Initial Custody Adjustment​

This transaction type (INITIAL_CUSTODY_ADJUSTMENT) exists to handle the specific case where position information needs to be used as an initial adjustment transaction. This case is common when you need to set a cut-off date for a position due to missing or inaccurate past transaction information (prior to the cut-off date). In this case, it is recommended to use this transaction type instead of a simple buy.

Besides giving the adjustment a dedicated transaction type, which makes it easier to identify and segregate, it does not require price information (the transaction's price field is optional). If the price is not provided, Gorila will use the security's market closing price on the transaction date.

Another effect is that, if there happens to be an open position prior to the transaction date, it is automatically closed and reopened by the transaction.

Example: Initial Custody Adjustment: INITIAL_CUSTODY_ADJUSTMENT

Position Close​

The POSITION_CLOSE transaction can be used to indicate that a position was closed (all the custody was sold) on a specific date. There is no need to provide the quantity sold: we calculate the custody on the transaction date and generate a sale for the exact quantity, so as to ensure that the position ends the day "zeroed". Since only funds and banking bonds (CDB, LCI, LCA, LIG, LF, etc.) are eligible for this type, the price parameter is optional. If the price is not provided in the request, the day's closing price will be used (eligible securities can only be traded at the closing price). The most suitable use case is when the transaction information does not have all the necessary decimal places, leaving residues in the position caused by mathematical imprecision at the time of the sale. It is also worth noting that, if a transaction dated before the position close transaction is added to the portfolio afterwards, the sale quantity of the position close transaction will be recalculated to reflect what is needed to ensure the full sale.

Example: Position Close: POSITION_CLOSE

Stock Subscription Exercise​

⚠️ Not implemented yet. Coming soon.

A stock subscription receipt is a document that proves an investor's right to acquire shares of a company at a price below market value. It contains information such as the company name, the number of shares the investor is entitled to buy, the subscription price, the expiry date and the conditions associated with the subscription.

The receipt is exercised when the holder decides to buy the shares at the subscription price specified in the receipt. In Gorila, since this depends on a choice to be exercised, inserting the subscription receipt operation is required. On the receipt's expiry date, it will be automatically converted into the security in question.

Example: Stock Receipt Exercise: SUBSCRIPTION_EXERCISE