# GorilaCORE > GorilaCORE is Gorila's investment portfolio API. You send the transactions of your clients' portfolios, and GorilaCORE prices the securities, applies corporate actions and other events, builds the positions and calculates the metrics: net asset value (NAV), profit and loss (P&L), time-weighted return (TWR), internal rate of return (IRR), allocation, liquidity and risk. It covers the Brazilian market (stocks, funds, government bonds, banking bonds, private credit, derivatives) and securities listed in the United States. This file indexes the English documentation of GorilaCORE for language models and AI agents. The documentation is also available in Portuguese: [llms.txt in Portuguese](https://gorila.com.br/core/llms.txt). The API is RESTful, takes and returns JSON, and is described by a public, live [OpenAPI spec](https://core.gorila.com.br/docs/json) that always matches the deployed API. The [API reference](https://gorila.com.br/core/en/api) is rendered by the browser, with JavaScript. Without a browser, read each operation in the spec (a JSON of about 400 KB), searching for the operation name (the `operationId`, such as `Create Portfolio`) or for the method and path. Instructions for AI agents: - Send requests to `https://core.gorila.com.br`. Authenticate every request with the organization's API key in the `Authorization` header, as the key itself (no `Bearer` prefix). API keys belong to an [organization](https://gorila.com.br/core/en/docs/core-concepts/organization), and what the organization creates is visible only to its keys. To get a key, a company [requests access](https://gorila.com.br/core/#form). - Use only the parameters and values the spec defines: before building a request, check the required parameters and the accepted values of each enum in it. - Follow the integration order: create a [portfolio](https://gorila.com.br/core/en/api#tag/portfolios/POST/portfolios) for each client and store its `portfolioId` next to the client in your system; [create the transactions](https://gorila.com.br/core/en/api#tag/transactions/POST/portfolios/{portfolioId}/transactions); then query the metrics. The [Quick Start](https://gorila.com.br/core/en/docs/quickstart) shows the whole flow with code. - Processing is asynchronous. A new or edited transaction, and its portfolio, are `PROCESSING` until the engine reflects them; read the metrics once the portfolio `status`, in [Read Portfolio by ID](https://gorila.com.br/core/en/api#tag/portfolios/GET/portfolios/{portfolioId}), is `COMPLETED`. - Send the `idempotency-key` header on Create Transaction, with the operation's ID in your system, so that a retried request doesn't create the transaction twice. A key already used returns `409`, with the `transactionId` of the existing transaction. - Most securities are managed by Gorila: find them with [List Securities](https://gorila.com.br/core/en/api#tag/securities/GET/securities), by name or by identifiers such as the ISIN or, for funds, the CNPJ. Banking bonds and similar securities (CDB, LCI, LCA, LF, DPGE, repurchase agreements, P2B and others), stock forwards, investment clubs, managed funds and custom securities must first be created with [Create Security](https://gorila.com.br/core/en/api#tag/securities/POST/securities), which returns the `securityId`. - In a transaction, identify the security in `security` by its `id` (the `securityId`) or, depending on the security type, by its `isin` or `cnpj` (funds); the [Transactions - Examples](https://gorila.com.br/core/en/docs/core-concepts/transaction_examples) page shows the identifiers each type accepts. Identify the custodian in `brokerId`, usually the institution's CNPJ ([List Brokers](https://gorila.com.br/core/en/api#tag/brokers/GET/brokers)). - Offshore securities (only those listed in the United States): send the transaction's price and fees in USD and the USDBRL rate in `exchangeRate`. - Don't record dividends, interest, amortizations, splits or maturities as transactions. GorilaCORE generates these [security events](https://gorila.com.br/core/en/docs/securities/security_event) itself. Custom securities are the exception: register their events with [Create Security Event](https://gorila.com.br/core/en/api#tag/security-events/POST/securities/{securityId}/events). - Rates, returns and percentages are decimals (`0.045` is 4.5%). Dates are `YYYY-MM-DD`. Values carry a `currency`; P&L, returns and positions are always in BRL. - Time series take `startDate`, `endDate` and `frequency` (`DAILY`, `MONTHLY`, `YEARLY` or `INTERVAL`); returns and P&L also take `seriesType` (`PER_PERIOD` or `ACCUMULATED`). Responses bring the `timeseries` and an `interval` with the value for the whole period. Use `frequency=INTERVAL` when only that value is needed. - To break down or narrow a metric, use the API's parameters instead of adding up or filtering positions in your code: `groupBy` on the position endpoints (by broker, security, security type, asset class or classification level) and the filters `brokerId`, `securityId`, `securityType`, `securityAssetClass`, `securityClassification` and `excludeSecurityClassification`. - Use the TWR to evaluate and compare performance, including against benchmarks: it ignores contributions and redemptions. Use the P&L and the IRR for the investor's financial result. - To compare with a benchmark, find its ID with [List Benchmarks](https://gorila.com.br/core/en/api#tag/benchmarks/GET/benchmarks) and query [Read Benchmark by ID](https://gorila.com.br/core/en/api#tag/benchmarks/GET/benchmarks/{benchmarkId}) with the same period, frequency and series type as the portfolio. `multiplier` and `spread` express targets such as "120% of CDI" (`1.2`) and "IPCA + 3%" (`0.03`). - For a client with several portfolios, create an [economic group](https://gorila.com.br/core/en/docs/core-concepts/economic_groups) (up to 10 portfolios): the same metrics are available for the group as a whole. - List endpoints are paginated: pass `limit` (100 by default, 1000 at most) and follow the `next` URL of the response until it is `null`. - Past the request limit, the API returns `429`. The limits follow the organization's contracted volume: wait before trying again. ## Get started - [Introduction](https://gorila.com.br/core/en/docs/intro): What GorilaCORE is and how the API works. - [Quick Start](https://gorila.com.br/core/en/docs/quickstart): Authenticate, create a portfolio, add transactions and read NAV, P&L and TWR, with Python and JavaScript code. - [Building an application](https://gorila.com.br/core/en/docs/use-cases/building-an-application): Which endpoints feed each component of an investment app: summary, allocation, performance chart and positions. - [Enhancing your reports](https://gorila.com.br/core/en/docs/use-cases/enhancing-your-reports): A monthly client report built block by block, with the endpoint and parameters behind each number. - [Integrating banking bonds](https://gorila.com.br/core/en/docs/use-cases/integrating-banking-bonds): Register CDBs, LCIs, LCAs and other banking bonds and load their transactions, and the data problems to watch for. ## Core concepts - [Organization](https://gorila.com.br/core/en/docs/core-concepts/organization): The company with access to GorilaCORE; owns the API keys and the resources it creates. - [Portfolio](https://gorila.com.br/core/en/docs/core-concepts/portfolio): Stores a client's transactions; status, cash components, automatic contributions and redemptions (`autoRnC`), automatic come-cotas and investment profile. - [Economic Group](https://gorila.com.br/core/en/docs/core-concepts/economic_groups): Up to 10 portfolios analyzed as one consolidated portfolio. - [Investment Profile](https://gorila.com.br/core/en/docs/core-concepts/investment_profile_and_target_allocation): Target allocation by security classification, and how a portfolio's compliance with it is calculated. - [Security](https://gorila.com.br/core/en/docs/core-concepts/security): The security types, which ones Gorila manages and which ones must be created, and how to create them. - [Transaction](https://gorila.com.br/core/en/docs/core-concepts/transaction): The transaction types (regular, come-cotas, option exercise, custody transfer, initial custody adjustment, position close), statuses and the idempotency key. - [Transactions - Examples](https://gorila.com.br/core/en/docs/core-concepts/transaction_examples): A request example for each security type, with the security identifiers it accepts. Long page: open it for the security type at hand. - [Position](https://gorila.com.br/core/en/docs/core-concepts/position): The quantity of a security at a broker on a date, and the position endpoints. - [Broker](https://gorila.com.br/core/en/docs/core-concepts/broker): The institution that holds a position in custody, identified by `brokerId` (usually its CNPJ). - [Issuer](https://gorila.com.br/core/en/docs/core-concepts/issuer): The entity that issues a security, identified by `issuerId`. - [Benchmark](https://gorila.com.br/core/en/docs/core-concepts/benchmark): Market references such as CDI, SELIC, IPCA and IBOVESPA, modifiers (`multiplier`, `spread`) and the calculation method. - [Currency](https://gorila.com.br/core/en/docs/core-concepts/currency): How values in other currencies are returned, and which values are always converted to BRL. ## Securities - [Custom Security](https://gorila.com.br/core/en/docs/securities/custom_securities): Securities your organization creates and prices, such as real estate or stakes in private companies, with their prices and events. - [Security Classification](https://gorila.com.br/core/en/docs/securities/security_classification): The 4-level class tree behind allocation views, filters (`securityClassification`, `excludeSecurityClassification`) and `groupBy`, and custom classifications. - [Security Events](https://gorila.com.br/core/en/docs/securities/security_event): Corporate actions and other events (dividends, interest, amortizations, splits, maturities) and their effect on positions. - [Security Metrics](https://gorila.com.br/core/en/docs/securities/security_kpi): Return and risk of an isolated security, outside any portfolio. - [Price Conversion](https://gorila.com.br/core/en/docs/securities/price_conversion): The price and quantity that correspond to a trade's date and financial amount (or rate). ## Analysis and metrics - [Market Value](https://gorila.com.br/core/en/docs/metrics/market_value): The value of each position at market prices, with `groupBy` for allocation views. - [Exposure](https://gorila.com.br/core/en/docs/metrics/exposure): The amount subject to price variation; differs from market value for futures and forwards (`marketValueType`). - [Average Price](https://gorila.com.br/core/en/docs/metrics/average_price): The average acquisition price of a position. - [Invested Amount](https://gorila.com.br/core/en/docs/metrics/invested_amount): The acquisition cost of the units still held. - [Net Asset Value (NAV)](https://gorila.com.br/core/en/docs/metrics/nav): The portfolio's total value, including cash and provisions, over time. - [Profit & Loss (P&L)](https://gorila.com.br/core/en/docs/metrics/pnl): The nominal result of a portfolio or position over a period. - [Time-Weighted Return (TWR)](https://gorila.com.br/core/en/docs/metrics/twr): How returns are calculated, `seriesType`, `frequency` and the return basis (`GROSS_UP` or `GROSS`). - [Internal Rate of Return (IRR)](https://gorila.com.br/core/en/docs/metrics/irr): The money-weighted return of each position, which accounts for the size and timing of cash flows. - [Dividend Yield](https://gorila.com.br/core/en/docs/metrics/dividend_yield): The income a security paid relative to its price. - [Drawdown](https://gorila.com.br/core/en/docs/metrics/drawdown): How far the accumulated return is below its peak. - [Volatility and Sharpe Ratio](https://gorila.com.br/core/en/docs/metrics/volatility_and_sharpe_ratio): Risk and risk-adjusted return of a portfolio or security, and the calculation window (`calculateWindow`). - [Liquidity](https://gorila.com.br/core/en/docs/metrics/liquidity): How long each position takes to become cash, grouped into day ranges. - [Portfolio Security Events](https://gorila.com.br/core/en/docs/metrics/portfolio_security_event): The events that affected a portfolio's positions over a period. ## Main API operations - [OpenAPI spec](https://core.gorila.com.br/docs/json): The complete, live, machine-readable description of the API (JSON), with parameters, enums and schemas. It has every operation, including the many this list doesn't mention. - [API reference](https://gorila.com.br/core/en/api): The same spec in an interactive page, with request and response examples. It needs a browser with JavaScript. - [Create Portfolio](https://gorila.com.br/core/en/api#tag/portfolios/POST/portfolios): `POST /portfolios` - [Read Portfolio by ID](https://gorila.com.br/core/en/api#tag/portfolios/GET/portfolios/{portfolioId}): `GET /portfolios/{portfolioId}`, with the processing `status`. - [Create Transaction](https://gorila.com.br/core/en/api#tag/transactions/POST/portfolios/{portfolioId}/transactions): `POST /portfolios/{portfolioId}/transactions` - [List Transactions](https://gorila.com.br/core/en/api#tag/transactions/GET/portfolios/{portfolioId}/transactions): `GET /portfolios/{portfolioId}/transactions` - [List Securities](https://gorila.com.br/core/en/api#tag/securities/GET/securities): `GET /securities` - [Create Security](https://gorila.com.br/core/en/api#tag/securities/POST/securities): `POST /securities` - [Price Conversion](https://gorila.com.br/core/en/api#tag/price-conversions/POST/securities/price-conversions): `POST /securities/price-conversions` - [List Brokers](https://gorila.com.br/core/en/api#tag/brokers/GET/brokers): `GET /brokers` - [List Positions](https://gorila.com.br/core/en/api#tag/positions/GET/portfolios/{portfolioId}/positions): `GET /portfolios/{portfolioId}/positions` - [List Position Market Values](https://gorila.com.br/core/en/api#tag/market-values/GET/portfolios/{portfolioId}/positions/market-values): `GET /portfolios/{portfolioId}/positions/market-values` - [Read Net Asset Value](https://gorila.com.br/core/en/api#tag/net-asset-value/GET/portfolios/{portfolioId}/nav): `GET /portfolios/{portfolioId}/nav` - [Read Profit & Losses](https://gorila.com.br/core/en/api#tag/profit--losses/GET/portfolios/{portfolioId}/pnl): `GET /portfolios/{portfolioId}/pnl` - [Read Time-Weighted Return](https://gorila.com.br/core/en/api#tag/time-weighted-return/GET/portfolios/{portfolioId}/twr): `GET /portfolios/{portfolioId}/twr` - [List Benchmarks](https://gorila.com.br/core/en/api#tag/benchmarks/GET/benchmarks): `GET /benchmarks` - [Read Benchmark by ID](https://gorila.com.br/core/en/api#tag/benchmarks/GET/benchmarks/{benchmarkId}): `GET /benchmarks/{benchmarkId}` - [Other API operations](https://core.gorila.com.br/docs/json): This list mentions only the main operations. The API has many others, all described in the spec, for example: the metrics and positions of an economic group, under `/economic-groups/{economicGroupId}/...`, each one mirroring the equivalent portfolio operation, under `/portfolios/{portfolioId}/...`; a portfolio's risk (Read Volatility, Read Sharpe Ratio and Read Drawdown); the breakdown by position (IRR, P&L, TWR, average price, invested amount, liquidity and dividend yield, as in List Position Internal Rate of Return); editing and deleting portfolios and transactions (such as Update Transaction by ID and Delete Transaction by ID); investment profiles and target allocation (Create Investment Profile, Get Portfolio Target Allocation) and security classifications (Create Security Classification); the prices and events of custom securities (Upsert Security Prices, Create Security Event), the metrics of an isolated security (Read Security Time-Weighted Return) and issuers (List Issuers). ## Optional - [Changelog](https://gorila.com.br/core/en/changelog): Every GorilaCORE update since July 2023, one post per update. - [Request access](https://gorila.com.br/core/#form): Contact form to get an organization and an API key.