Instruments API

Use the Instruments API to manage the Instruments that will be used with the Ledgers.

Refer to Instruments API in the Requests and Responses page for more information about the parameters.

Create an Instrument

POST /v1/organizations/{{id}}/ledgers/{{id}}/instruments

Use this endpoint to create an Instrument that will be used with the transactions. Each Instrument must be created one at a time.

Each instrument has decimal place settings and other specific parameters that will be created individually.

You must create the Instrument twice with different configurations to use the same instrument (e.g. BTC) on two Ledgers with different configurations.

Headers

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

Request body

{
  "name": "Bitcoin",
  "type": "crypto",
  "code": "BTC",
  "metadata": {
    "internalExchangeAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "internalExchangeCustody": "Binance US"
  },
  "status": {
    "code": "ACTIVE", 
    "description": null
  }
}

Response codes

201

{
  "id": "bb907427-5a8c-4622-b1ce-801b70e40d0c",
  "organizationId": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "ledgerId": "77b0fb8b-1bd9-4810-9c6d-7e80064fab0c",
  "name": "Bitcoin",
  "type": "crypto",
  "code": "BTC",
  "metadata": {
    "internalExchangeAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "internalExchangeCustody": "Binance US"
  },
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "createdAt": "2024-02-08T17:03:12+0300",
  "updatedAt": "2024-02-08T17:03:12+0300",
  "deletedAt": null
}

400

{
  "code": "0004",
  "title": "Code Uppercase Requirement",
  "description": "The code must be in uppercase. Please send the code in uppercase format."
}

400

{
  "code": "0005",
  "title": "Currency Code Standard Compliance",
  "description": "Currency-type instruments must adhere to the ISO-4217 standard. Please use a currency code that follows ISO-4217 guidelines."
}

400

{
  "code": "0033",
  "title": "Invalid Code Format",
  "description": "The 'code' field must be alphanumeric, in upper case, and must contain at least one letter. Please provide a valid code."
}

409

{
  "code": "0003",
  "title": "Instrument Name or Code Duplicate",
  "description": "An instrument with the same name or code already exists in your ledger. Please modify the name or code of your new instrument."
}

---

Retrieve all Instruments

GET /v1/organizations/{{id}}/ledgers/{{id}}/instruments?type={{type}}

Use this endpoint to retrieve the information of all Instruments to which a user has access.

Headers

Name	Value
Authorization	Bearer <token>

Query parameters

Name	Type	Description
type	String	The type of instrument.
code	String	The code that represent the instrument.
status	Array	An object containing information about the status.
metadata	Array	An object containing metadata information.

Response codes

200

[
  {
    "id": "bb907427-5a8c-4622-b1ce-801b70e40d0c",
    "ledgerId": "e04cdf8b-0c8e-451e-881d-74d409936aee",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "Bitcoin",
    "type": "crypto",
    "code": "BTC",
    "status": {
      "code": "002",
      "description": "Blocked"
    },
    "metadata": {
      "internalExchangeAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "internalExchangeCustody": "Binance US"
    }
  },
  {
    "id": "f9e838d6-d3a7-4975-b681-613999537d2e",
    "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "Real",
    "type": "currency",
    "code": "BRL",
    "status": {
      "code": "001",
      "description": "Active"
    },
    "metadata": {
      "localBank": "c6"
    }
  },
  {
    "id": "174ef9b1-21b3-40ce-a008-2a8e6b0b532a",
    "ledgerId": "8357fd78-81a8-4075-a399-863b3d39779e",
    "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
    "name": "Chainlink",
    "type": "crypto",
    "code": "LINK",
    "status": {
      "code": "001",
      "description": "Active"
    },
    "metadata": {
      "priceIn2025": 200.98,
      "priceCurrency": "USD"
    }
  }
]

400

{
  "code": "0017",
  "title": "Invalid Script Error",
  "description": "The script provided in the request is invalid or in an unsupported format. Please verify the script and try again."
}

---

Retrieve Instrument by id

GET /v1/organizations/{{id}}/ledgers/{{id}}/instruments/{{id}}

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

Headers

Name	Value
Authorization	Bearer <token>

Response codes

200

{
  "id": "bb907427-5a8c-4622-b1ce-801b70e40d0c",
  "ledgerId": "e04cdf8b-0c8e-451e-881d-74d409936aee",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "Bitcoin",
  "type": "crypto",
  "code": "BTC",
  "status": {
    "code": "001",
    "description": "Active"
  },
  "metadata": {
    "internalExchangeAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "internalExchangeCustody": "Binance US"
  }
}

400

{
  "code": "0017",
  "title": "Invalid Script Error",
  "description": "The script provided in the request is invalid or in an unsupported format. Please verify the script and try again."
}

---

Update an Instrument

PATCH /v1/organizations/{{id}}/ledgers/{{id}}/instruments/{{id}}

Use this endpoint to edit and update the information of a specific Instrument. When you update an Instrument, the following fields can be edited:

• name

• status

• metadata

When updating the metadata object, all previous key-value pairs must be included in the update, or they will be removed.

Headers

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

Request body

{
  "name": "Brazilian Real",
  "status": {
    "code": "003",
    "description": "Pre-launch"
  },
  "metadata": {
    "cfo": "Satoshi Nakamoto"
  }
}

Response codes

200

{
  "id": "f9e838d6-d3a7-4975-b681-613999537d2e",
  "ledgerId": "c3a89e04-b1cd-4df8-a5f9-0bb077e07e6d",
  "organizationId": "5f3a4c55-8b28-4276-bed7-f7c8a4bb44e8",
  "name": "Brazilian Real",
  "type": "currency",
  "code": "BRL",
  "status": {
    "code": "003",
    "description": "Pre-launch"
  },
  "metadata": {
    "cfo": "Satoshi Nakamoto"
  },
  "createdAt": "2024-02-08T17:03:12+0300",
  "updatedAt": "2024-02-08T17:03:12+0300",
  "deletedAt": null
}

400

{
  "code": "0017",
  "title": "Invalid Script Error",
  "description": "The script provided in the request is invalid or in an unsupported format. Please verify the script and try again."
}

---

Delete an Instrument

DELETE /v1/organizations/{{id}}/ledgers/{{id}}/instruments/{{id}}

Use this endpoint to deactivate a specific Instrument.

An instrument can only be deleted if no balance is available in its ledger accounts. Therefore, all remaining amounts must be moved to the External Account before deleting an instrument.

Headers

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

Response codes

204

400

{
  "code": "0017",
  "title": "Invalid Script Error",
  "description": "The script provided in the request is invalid or in an unsupported format. Please verify the script and try again."
}

404

{
  "code": "0007",
  "title": "Invalid Script Error",
  "description": "Entity not found."
}