Instrument rates API

Use the Instrument Rates API to manage exchange rates between instrument pairs.

Create an instrument rate

POST /v1/organizations/{{id}}/ledgers/{{id}}/instrument-rates

Create the exchange rate for a pair of instruments.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
    "baseInstrumentCode": "BRL",
    "counterInstrumentCode": "BTC",
    "amount": 35000000,
    "scale": 2,
    "source": "Chainlink database",
    "status": {
        "code": "My custom ACTIVE code",
        "description": "My description"
    },
    "metadata": {
        "updateCycle": 300,
        "urgent": true
    }
}

Response codes

201

{
    "id": "d0aa3885-0f9d-4856-9ca8-7da4fe6e2a95",
    "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "baseInstrumentCode": "BRL",
    "counterInstrumentCode": "BTC",
    "amount": 35000000,
    "scale": 2,
    "source": "Chainlink database",
    "status": {
        "code": "My custom ACTIVE code",
        "description": "My description"
    },
    "metadata": {
        "updateCycle": 300,
        "urgent": true
    },
    "createdAt": "2024-01-29T00:12:00+0300",
    "updatedAt": "2024-01-29T00:12:00+0300",
    "deletedAt": null
}

400

{
  "code": "0028",
  "title": "Instrument pair already exists",
  "description": "There is already a pair for the instruments {{baseInstrumentCode}}{{counterInstrumentCode}} with the id {{instrument_rates.id}}. Try to update it instead of create."
}

---

Retrieve all instrument rates

GET /v1/organizations/{{id}}/ledgers/{{id}}/instrument-rates

Use this endpoint to retrieve the information of all instrument exchange rate pairs.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Query parameters

Name	Type	Description
baseInstrumentCode
counterInstrumentCode
source
metadata

Response codes

200

[
    {
        "id": "d0aa3885-0f9d-4856-9ca8-7da4fe6e2a95",
        "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
        "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
        "baseInstrumentCode": "BRL",
        "counterInstrumentCode": "BTC",
        "amount": 35000000,
        "scale": 2,
        "source": "Chainlink database",
        "status": {
            "code": "My custom ACTIVE code",
            "description": "My description"
        },
        "metadata": {
            "updateCycle": 300,
            "urgent": true
        }
    },
    {
        "id": "8d47ade1-dfe3-4036-9000-a0ff045715e4",
        "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
        "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
        "baseInstrumentCode": "BTC",
        "counterInstrumentCode": "USD",
        "amount": 6900000,
        "scale": 2,
        "source": "Coinmarketcap",
        "status": {
            "code": "ACTIVE",
            "description": null
        },
        "metadata": {
            "anyKey": "anyValue"
        }
    }
]

---

Retrieve an instrument rate by id

GET /v1/organizations/{{id}}/ledgers/{{id}}/instrument-rates/{{id}}

Use this endpoint to retrieve the information of a specific exchange rate pair using the identifier (id).

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Response codes

200

{
    "id": "8d47ade1-dfe3-4036-9000-a0ff045715e4",
    "baseInstrumentCode": "BRL",
    "counterInstrumentCode": "BTC",
    "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "amount": 35000000,
    "scale": 2,
    "source": "Chainlink database",
    "status": {
        "code": "ACTIVE",
        "description": null
    },
    "metadata": {
        "updateCycle": 300,
        "urgent": true
    }
}

400

{
    "code": "0007",
    "title": "Entity not found",
    "description": "Entity not found for the ID informed. Check if you are sending the correct ID for the entity that you are managing."
}

---

Update an instrument rate

PATCH /v1/organizations/{{id}}/ledgers/{{id}}/instrument-rates/{{id}}

Use this endpoint to edit and update the information of a specific instrument exchange rate. When you update a Product, the following fields cannot be edited:

• createdAt

• updatedAt

• deletedAt

When updating the metadata object, all previous key-value pairs must be included in the update, or they will be removed. Check the Metadata section for more information.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Request body

{
    "source": "my head",
    "status": {
        "code": "New code",
        "description": "New description"
    },
    "metadata": {
        "whoAmI": "Jhon Doe"
    }
}

Response codes

200

{
    "id": "8d47ade1-dfe3-4036-9000-a0ff045715e4",
    "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "baseInstrumentCode": "BRL",
    "counterInstrumentCode": "BTC",
    "amount": 35000000,
    "scale": 2,
    "status": {
        "code": "New code",
        "description": "New description"
    },
    "status": "ACTIVE",
    "metadata": {
        "whoAmI": "Jhon Doe"
    },
}

400

{
    "code": "0007",
    "title": "Entity not found",
    "description": "Entity not found for the ID informed. Check if you are sending the correct ID for the entity that you are managing."
}

---

Delete an instrument rate

DELETE /v1/organizations/{{id}}/ledgers/{{id}}/instrument-rates/{{id}}

Use this endpoint to delete a specific instrument exchange rate. When you do this, the "status" will change to "INACTIVE" and the "deletedAt" == "current_timestamp()".

Headers

Name	Value
Authorization	Bearer <token>

Response codes

204

404

{
  "code": "0007",
  "title": "Entity not found"
  "description": "Entity not found for the ID informed. Check if you are sending the correct ID for the entity that you are managing."
}