The new POSITION_CLOSE transaction type closes a position on a given date without requiring the quantity sold, which avoids leftover residues when the transaction data lacks all the decimal places.

When creating a transaction with Create Transaction and type equal to POSITION_CLOSE, provide the date (transactDate), the broker (brokerId) and the security (security). Gorila calculates the custody on that date and generates a sale of the exact quantity, so that the position ends the day zeroed. If a transaction dated before the close is added later, the sale quantity is recalculated.

The type is available for funds and banking bonds (CDB, LCI, LCA, LF, etc.). The price field is optional: if it is not provided, the day's closing price is used. Fees can be provided in fees.

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

{
  "type": "POSITION_CLOSE",
  "transactDate": "2023-06-30",
  "brokerId": "18945670000146",
  "security": {
    "id": 2407939
  }
}

Learn more in Transaction and in the Position Close example.

Investment clubs can now be registered in GorilaCORE with the new INVESTMENT_CLUB security type and then used in your portfolios' transactions.

Like banking bonds and custom securities, an investment club needs to be created before receiving transactions. Use the Create Security endpoint with type equal to INVESTMENT_CLUB, providing a name (name), description (description), asset class (assetClass) and initial date (initialDate). The cnpj field is optional.

As with custom securities, the club's quota value is provided by your organization, through the price endpoints:

• Upsert Security Prices: creates or updates prices.
• List Security Prices: lists the registered prices.
• Delete Security Prices: deletes the price of a specific date.

Learn more in Security.

You can now search portfolios by name directly in the portfolio list.

The List Portfolios endpoint accepts the new optional search parameter, which filters the returned portfolios by name. The search term must have at least 3 characters.

GET https://core.gorila.com.br/portfolios?search=Silva

Learn more in Portfolio.

You can now delete custom securities you no longer use, as well as the price of a custom security on a specific date.

• Delete Security by ID: deletes a custom security. Deletion is only allowed if the security has no transactions in any portfolio; otherwise, the request is rejected.
• Delete Security Prices: deletes the price of a custom security on the date provided in referenceDate.

Learn more in Custom Security.

The portfolio list now returns the processing status of each portfolio, so you can track several portfolios in a single call.

Each record returned by List Portfolios now includes the status field (PROCESSING, COMPLETED or INVALID), which was previously available only in Read Portfolio by ID. A portfolio is COMPLETED when all of its transactions have been processed and are reflected in its positions and metrics.

Since 2024-12-27, Create Portfolio and Update Portfolio by ID also return the full portfolio, including the status field.

Learn more in Portfolio.

Banking bonds can now be created with the new P2B_LENDING type, to represent P2B (peer-to-business) lending operations.

In the Create Security endpoint, send bankingBondType equal to P2B_LENDING when creating a fixed-rate (FIXED_RATE_BANKING_BOND) or floating-rate (FLOATING_RATE_BANKING_BOND) banking bond. The resulting security has the P2B_LENDING type and, like the other banking bonds, can then be used in transactions through the returned securityId.

Learn more in Security.

Besides the organization's API keys, the API now accepts Personal Access Tokens (PATs): personal keys that grant access with the permissions of the user who owns them.

The two credentials differ in scope:

• Organization API key: associated with the organization, it grants access to the organization's portfolios and resources.
• PAT: associated with a user, it carries that user's permissions. Requests authenticated with a PAT only see the portfolios and resources the user has access to.

A PAT is generated by the user in the Gorila platform, not through the API. It is sent the same way as an API key, in the Authorization header, and can be recognized by the pat_ prefix:

curl --request GET \
  --url https://core.gorila.com.br/portfolios \
  --header 'Authorization: pat_<token>'

Learn more about API keys in Organization.

You can now choose how a benchmark's return is accounted for on the first day of the series, with the new calculationMethod parameter.

The Read Benchmark by ID endpoint accepts the optional calculationMethod parameter:

• INDEX (default): accounts for the return from the first day (startDate) for all benchmarks.
• INTEREST: does not account for the return of the first day for any benchmark.
• AUTO: does not account for the first day for fixed income benchmarks (such as CDI and SELIC), but does for the others (such as IBOVESPA or USDBRL).

Before this change, series were always calculated with the AUTO behavior. To keep the previous results, send calculationMethod=AUTO.

Learn more in Benchmark.

Transactions and portfolios now return a status field, so you can tell whether position and metric calculations already reflect the transactions you created or edited.

The field takes the values PROCESSING, COMPLETED or INVALID and is returned by the following endpoints:

• Transactions: Create Transaction, List Transactions and Read Transaction by ID.
• Portfolios: Read Portfolio by ID.

Right after a transaction is created or edited, its status is PROCESSING while Gorila performs the calculations and checks. Once they are done, the status changes to COMPLETED. A portfolio becomes COMPLETED when all of its transactions have been processed. Before querying a portfolio's metrics, check that its status is already COMPLETED.

Learn more in Transaction and Portfolio.

You can now query the closed positions of a portfolio, in addition to the open ones, and each position now reports its state.

The List Positions endpoint accepts the new positionState parameter, with the values OPEN (default, open positions only), CLOSED (closed positions only) or ALL (open and closed positions). Each position in the response also includes the new state field, with the value OPEN or CLOSED. A position is closed when its quantity has been fully zeroed out.

Learn more in Position.

You can now send an idempotency key when creating transactions. It ensures that the same transaction is not recorded twice, for example, when a request is retried after a network failure or a timeout.

The Create Transaction endpoint accepts the optional idempotency-key header: a unique identifier for the transaction, generated by your system (such as a UUID or the operation's code in your database).

• The key is unique per portfolio. 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 (idempotency key already used).
• Without the header, each request creates a new transaction, even if the data is identical.

Learn more in Transaction.

Your organization can now create custom securities to represent investments that are not in Gorila's database, such as real estate or stakes in private companies, and provide their prices.

To create a custom security, use the Create Security endpoint with the CUSTOM type, informing name, description, assetClass and initialDate (maturityDate is optional). The response returns the new security's id, which you use to register prices and transactions.

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

{
  "type": "CUSTOM",
  "name": "Apartment",
  "description": "Apartment located in São Paulo",
  "assetClass": "TANGIBLE",
  "initialDate": "2022-04-04"
}

Since these securities have no market source, the organization provides their prices: use Upsert Security Prices to send a list of prices (prices, with referenceDate and price) and List Security Prices to read them. The prices apply to every portfolio in your organization that holds the security. Custom securities are available only to your organization's API keys.

Learn more in Custom Security.

The List Security Event Types endpoint is now available: it lists the security event types handled by Gorila, such as dividends, amortizations and stock bonuses.

These types classify the events that affect portfolio positions, such as those listed by List Security Events. The results are paginated (limit and pageToken), and the search parameter filters the types by part of their name or information.

Learn more in Security Events.

You can now list the security events, such as dividends and stock bonuses, that affected the positions of a portfolio over a period.

The List Security Events endpoint receives the period in startDate and endDate and returns paginated results (limit and pageToken). Each event informs the security and the broker, the event type (eventType), the ex-date (eventDate) and the payment date (paymentDate). Depending on the event, the response also includes the unit value (unitValue) or, for events that deliver another security, the security received (receivedSecurity), the quantity received (receivedQuantity) and the factor applied to the position (eventFactor).

Learn more in Portfolio Security Events.

The new Price Conversion endpoint turns the information you know about a trade, such as the amount invested, into the price (price) and quantity (quantity) needed to create a transaction.

This is especially useful for banking bonds (CDB, LC, LCI, LCA, LF), whose transactions now require both price and quantity, instead of quantity only.

The request identifies the security (security, by id, isin or cnpj) and the trade date (date), along with the financial amount (notional) or, for CRI, CRA and debentures, the trade rate (multiplier or spread). Supported securities are banking bonds (CDB, LC, LCI, LCA, LF), all types of fund shares and corporate bonds (CRI, CRA and debentures).

For example, to convert BRL 10,000.00 invested in a fund:

// REQUEST
// POST https://core.gorila.com.br/securities/price-conversions

{
  "security": {
    "cnpj": "26673556000132"
  },
  "date": "2023-06-23",
  "notional": 10000
}

// RESPONSE

{
  "security": {
    "id": 2363053,
    "cnpj": "26673556000132",
    "name": "ALASKA INSTITUCIONAL FIA",
    "type": "FUNDQUOTE",
    "assetClass": "STOCKS"
  },
  "date": "2023-06-23",
  "price": 3.2519722,
  "quantity": 3075.0570377
}

The returned price and quantity are ready to use in the Create Transaction endpoint.

Learn more in Price Conversion.

We have revamped the GorilaCORE documentation to make it easier to model transactions, securities and metrics in your integration.

The Transaction page was rewritten and now details each transaction type, what it is for and when to use it. It links to the new Transaction Examples page, which shows how to create transactions for every security supported by Gorila.

The Internal Rate of Return (IRR) and Time-Weighted Return (TWR) pages now include examples that show the differences between the two metrics and when to use each one. The Net Asset Value (NAV), Profit & Loss (P&L), Average Price and Position pages were also expanded.

The Security page gained examples of how to create securities, such as banking bonds, and how to register transactions with them.

Finally, the API reference now includes links to the concept pages, so you can quickly understand the concepts used in each endpoint.

Security search now ranks results by relevance: the securities that best match your search terms appear first, so you no longer need to go through long lists to find the one you are looking for.

The change applies to searches made with the search parameter of the List Securities endpoint.

Learn more in Security.