# Instrument

This entity is a unique ID for a financial asset or security involved in a transaction.

# Instrument

#### **Table of Contents**

- [Description](#bkmrk-description)
- [Examples](#bkmrk-examples)
- [Cookbook](#bkmrk-cookbook)
- [F.A.Q.](#bkmrk-api-documentation)
- [API Documentation](#bkmrk-api-documentation)

#### **Description**

##### *Financial meaning*

Financial instruments are contracts that represent a financial asset for one party and a financial liability or equity instrument for another. They are used in investing, hedging, and speculative strategies across global financial markets.

Instruments can be categorized into equity instruments (e.g., stocks), debt instruments (e.g., bonds), derivatives (e.g., options, swaps), and hybrid instruments.

##### *Platform abstraction*

In the **Finmars** platform, the Instrument entity represents the complete set of [financial instruments](https://docs.finmars.com/books/entities/page/instrument "Instrument") under management. It serves as a central component for accounting, valuation, performance measurement, risk analysis, reconciliation, and reporting.

**Instruments are used in:**

- Identifying and tracking specific financial assets or securities involved in [transactions](https://docs.finmars.com/books/entities/page/transactions "Transactions")
- Linking related [transactions ](https://docs.finmars.com/books/entities/page/transactions "Transactions")where instruments and cash considerations are connected (via linked instruments)
- Ensuring accurate valuation and processing of asset movements
- Supporting [reconciliation ](https://docs.finmars.com/books/reports/chapter/reconciliation "Reconciliation")and [reporting ](https://docs.finmars.com/books/reports "Reports")of financial positions across [portfolios ](https://docs.finmars.com/books/entities/page/portfolio "Portfolio")and [accounts](https://docs.finmars.com/books/entities/page/accounts "Accounts")

#### **Examples**

**First part of table**

<table border="1" id="bkmrk-user-code-modified-a" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col></colgroup><tbody><tr><td>**User code**</td><td>**Modified at**</td><td>**Asset type**</td><td>**Country**</td><td>**PRC CCY**</td><td>**ACCR CCY**</td><td>**Short name**</td><td>**Name**</td></tr><tr><td>CH-BND-20394856</td><td>2025-02-10</td><td>Other</td><td>Colombia</td><td>USD</td><td>USD</td><td>CH-BND-20394856</td><td>Ms\_XX:20394856</td></tr></tbody></table>

**Second part of table**

<table border="1" id="bkmrk-public-name-mat%C2%A0-dt-" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col><col style="width: 12.5%;"></col></colgroup><tbody><tr><td>**Public name**</td><td>**MAT DT**</td><td>**MAT PRC**</td><td>**PRC MULT**</td><td>**ACCR MULT**</td><td>**INSTR TYPE**</td><td>**PMT SZ DTL**</td><td>**Notes**</td></tr><tr><td>20394856</td><td>9999-12-31</td><td>0.00</td><td>1.00</td><td>1.00</td><td>Portfolio</td><td>Default</td><td>  
</td></tr></tbody></table>

1. `<strong data-end="187" data-start="174">User code</strong>`: unique identifier assigned to the instrument. Used for internal reference and tracking.
2. `<strong data-end="326" data-start="311">Modified at</strong>`: date and time of the last modification to the instrument data.
3. `<strong data-end="450" data-start="436">Asset type</strong>`: classification of the instrument (e.g., Bond, Derivative, Real Estate). Determines behavior and processing rules in the system.
4. `<strong data-end="590" data-start="579">Country</strong>`: country of issuance or jurisdiction of the instrument's issuer. Important for regulatory and risk assessment purposes.
5. `<strong data-end="745" data-start="715">PRC CCY </strong><strong data-end="745" data-start="715">(Pricing Currency)</strong>`: the currency in which the instrument is quoted or priced. Used for valuation and financial reporting.
6. `<strong data-end="884" data-start="853">ACCR CCY (Accrual Currency)</strong>`: the currency used to calculate interest or accruals. May differ from pricing currency.
7. `<strong data-end="991" data-start="977">Short name</strong>`: abbreviated or condensed label for quick reference.
8. `<strong data-end="1097" data-start="1089">Name</strong>`: full name of the instrument, typically including issuer, coupon/yield, and maturity details.
9. `<strong data-end="1211" data-start="1196">Public name</strong>`: market-facing or external name of the instrument, often matching how it appears on exchanges or public reports.
10. `<strong data-end="1356" data-start="1330">MAT DT (Maturity Date)</strong>`: the date on which the instrument matures or principal is repaid. Key for fixed-income instruments.
11. `<strong data-end="1490" data-start="1462">MAT PRC (Maturity Price)</strong>`: the expected or agreed price of the instrument at maturity.
12. `<strong data-end="1629" data-start="1596">PRC MULT (Pricing Multiplier)</strong>`: factor applied to scale the market price to nominal or unit-based values (e.g., per 100 or per 1,000 units).
13. `<strong data-end="1779" data-start="1745">ACCR MULT (Accrual Multiplier)</strong>`: factor used to adjust accrual amounts. Helps handle non-standard periods or calculation rules.
14. `<strong data-end="1913" data-start="1881">INSTR TYPE (Instrument Type)</strong>`: instrument type code (e.g., BOND, STOCK, PORTFOLIO). Used for classification, logic, and filtering.
15. `<strong data-end="2049" data-start="2013">PMT SZ DTL (Payment Size Detail)</strong>`: specifies the payment structure (e.g., default). Supports payment schedule modeling.
16. `<strong data-end="2170" data-start="2161">Notes</strong>`: free-text field for comments or special handling notes related to the instrument.

#### **Cookbook**

##### *CRUD* 

**Create:** [How to Create a Instrument entity](https://docs.finmars.com/books/entities/page/how-to-create-an-instrument-entity "How to Create a Instrument entity")

##### *Use Cases*

What for it's used.

#### **F.A.Q.**

Frequently asked questions.

#### **API documentation**

Link to API documentation.

# How to Create an Instrument entity

## Prerequisites

We assume you have all prerequisites you may need, including:

1. If needed: the VPN is configured to access the Finmars resources
2. If needed: access to the Virtual Machine to work with the sensitive information
3. Must have: registered in Finmars in the needed region environment (self-registered or registered by Finmars)
4. Must have: having permissions set to allow continue with the Action in the Guide

## Creation of Register Entity

1. <span style="color: rgb(170, 170, 170); background-color: rgb(34, 34, 34);">Open the</span> ****“Data”**** <span style="color: rgb(170, 170, 170); background-color: rgb(34, 34, 34);">section in the left-hand side menu. Select the</span> ****“Instruments”**** <span style="color: rgb(170, 170, 170); background-color: rgb(34, 34, 34); white-space: pre-wrap;">entity from the list under </span>****Data****<span style="color: rgb(170, 170, 170); background-color: rgb(34, 34, 34);">.</span>  
    [![Снимок экрана 2025-05-07 051134.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/snimok-ekrana-2025-05-07-051134.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/snimok-ekrana-2025-05-07-051134.png)
2. ****Click the “+ Add” button****<span style="color: rgb(170, 170, 170); background-color: rgb(34, 34, 34); white-space: pre-wrap;"> located in the top-left corner of the portfolio list view. </span>A dropdown menu will appear offering four methods to add a new instrument:
    1. ****Add Blank****<span style="white-space: pre-wrap;"> – manual entry with a fully blank template.</span>
    2. ****Add Typical****<span style="white-space: pre-wrap;"> – pre-filled template with commonly used default values.</span>
    3. ****Import from File****<span style="white-space: pre-wrap;"> – bulk import instruments using a file.</span>
    4. ****Get from Provider****<span style="white-space: pre-wrap;"> – retrieve instrument data from a market data provider.</span>

[![Снимок экрана 2025-05-07 051324.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/snimok-ekrana-2025-05-07-051324.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/snimok-ekrana-2025-05-07-051324.png)

##### Option 1: Add Blank

This opens a completely blank form where you can manually input all instrument details.

[![image.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/yC7image.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/yC7image.png)  
  
Fill out the following fields as needed:

1. ****Instrument****<span style="white-space: pre-wrap;"> – full name or unique identifier (required).</span>
2. ****Instrument type****<span style="white-space: pre-wrap;"> – defines the kind of instrument (e.g., Bond, Stock, FX Forward, etc.).</span>
3. ****Asset Type**** – specifies the financial asset classification (e.g., Equity, Fixed Income).
4. ****Country**** – country of issuance of the instrument.
5. ****Accrual Size Clarification****<span style="white-space: pre-wrap;"> – optional explanation or note for accrual calculation basis.</span>
6. ****Pricing currency****<span style="white-space: pre-wrap;"> – the currency in which the instrument's market price is quoted.</span>
7. ****Accrued currency****<span style="white-space: pre-wrap;"> – the currency in which interest or other accruals are calculated and reported.</span>
8. ****Price multiplier**** – multiplier applied to the quoted price to calculate notional or total value (e.g., 100 if price is per 100 units).
9. ****Accrued multiplier****<span style="white-space: pre-wrap;"> – multiplier used to adjust the accrual value, typically to scale interest or dividend values appropriately.</span>
10. ****Maturity date****<span style="white-space: pre-wrap;"> – the date when the instrument is due to mature and be settled (e.g., for bonds or term deposits).</span>
11. ****Maturity price****<span style="white-space: pre-wrap;"> – the expected price or value at maturity, often used in valuation or final settlement (if applicable).</span>
12. ****Notes**** – any relevant internal comments or additional metadata for this instrument.
13. ****Identifiers****<span style="white-space: pre-wrap;"> – optional key-value fields such as ISIN, CUSIP, internal codes, etc., used to uniquely identify the instrument.</span>

<span style="white-space: pre-wrap;">Click </span>****“Create and Exit”****<span style="white-space: pre-wrap;"> to save and return to the list, or</span> ****“Create”****<span style="white-space: pre-wrap;"> to save and continue editing.</span>  
[![Снимок экрана 2025-05-07 051440.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/snimok-ekrana-2025-05-07-051440.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/snimok-ekrana-2025-05-07-051440.png)

## Option 2: Add Typical

This will load a pre-filled template with default values for typical instruments, which can be modified as needed. Use this option to speed up creation when working with commonly used instruments.  
[![image.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/oTGimage.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/oTGimage.png)

<span style="white-space: pre-wrap;">Click </span>****“Create and Exit”****<span style="white-space: pre-wrap;"> to save and return to the list, or</span> ****“Create”****<span style="white-space: pre-wrap;"> to save and continue editing.</span>

## Option 3: Import from File

Use this option to import multiple instruments into the system from a prepared file (e.g., Excel or CSV).

1. ****Name****<span style="white-space: pre-wrap;"> – provide a name for the import process).</span>
2. ****Import Scheme**** – select the appropriate scheme that matches the structure of your file. This determines how the system interprets and maps the data.
3. ****Browse**** – click this button to choose a file from your computer. Supported formats depend on the selected import scheme (e.g., .xlsx, .csv).  
    [![image.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/Yrnimage.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/Yrnimage.png)

<span style="white-space: pre-wrap;">After selecting the file, click </span>****“Validate”****<span style="white-space: pre-wrap;"> to check the file for errors and confirm it matches the selected scheme. If the validation is successful, click </span>****“Import”****<span style="white-space: pre-wrap;"> to load the instruments into the database.</span>

## Option 4: Get from Provider

Automatically pull instrument data from a connected market data provider.

[![image.png](https://docs.finmars.com/uploads/images/gallery/2025-05/scaled-1680-/7gTimage.png)](https://docs.finmars.com/uploads/images/gallery/2025-05/7gTimage.png)

<span style="white-space: pre-wrap;">After selecting the desired instrument, click the </span>****“Add”****<span style="white-space: pre-wrap;"> button to load it into the system.</span>