IBM Cloud API Docs

Introduction

The Simulated Instrument Analytics service supports the computation of the theoretical or market-calibrated valuation, and all relevant associated analytics, for investment securities such as equities, fixed income, and derivatives over an alternate set of market conditions.

Authentication

You authenticate to the API by using IAM. You can pass either a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. Learn more about IAM.

If you are using Simulated Instrument Analytics and you are also using Managed Financial Data as the data provider service, follow the steps that are described in Connecting to IBM Managed Financial Data API.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Methods

Compute mark-to-market for one or more instruments

Returns the values for the requested analytics for a given instrument.

GET /v2/mtm/{id-type}

Request

Path Parameters

  • ID Type

    Allowable values: [isin,sedol,ric]

Query Parameters

  • One or more instrument IDs. Separate IDs with commas.

  • Specify a three-letter currency code for reporting purposes.

  • curl --request GET  --url https://us-south.sia.cloud.ibm.com/v2/mtm/isin?ids=<id-of-instrument-1>,<id-of-instrument-2> --header 'Authorization-api-key: REPLACE_KEY_VALUE' --header 'Authorization-instance-id: REPLACE_UUID_VALUE'
  • var XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
    var request = new XMLHttpRequest()
    request.open("GET","https://us-south.sia.cloud.ibm.com/v2/mtm/isin?ids=<id-of-instrument-1>,<id-of-instrument-2> ")
    request.setRequestHeader("enctype", "string")
    request.setRequestHeader("accept", "application/json")
    request.setRequestHeader("content-type", "multipart/form-data")   
    request.setRequestHeader("Authorization-api-key", "REPLACE_KEY_VALUE")
    request.setRequestHeader("Authorization-instance-id", "REPLACE_UUID_VALUE")                      
    request.send()
    request.onload = () =>console.log(request.responseText) 
    
  • import requests
    headers = {
        'enctype': "string",
        'accept': "application/json",
        'content-type': "multipart/form-data",
        'Authorization-api-key': <REPLACE_KEY_VALUE>
        'Authorization-instance-id': <REPLACE_UUID_VALUE>
        }
    response = requests.get("https://us-south.sia.cloud.ibm.com/v2/mtm/isin?ids=<id-of-instrument-1>,<id-of-instrument-2>", headers=headers)
    response = requests.get(url,headers=headers)
    print(response.text)
    

Response

Status Code

  • Success. Returns an array of results for each valid instrument ID and the value for each specified analytic.

  • The request requires you to specify the API key in the request. Please refer to the Getting Started page for Simulated Instrument Analytics and resubmit.

  • The API key wasn't recognized. Verify that your API key is correct and resubmit.

  • The requested resource could not be found. See the error for more details

  • The requested method is not allowed.

  • Unexpected error. Contact your Simulated Instrument Analytics administrator. See the error for more details

Example responses
  • {
      "results": [
        {
          "Currency": "USD",
          "Simulation Date": "2018/10/16",
          "ID": "<instrument_1_ID>",
          "Value": "96.09038333",
          "Name": "<instrument_1_name>"
        },
        {
          "Currency": "USD",
          "Simulation Date": "2018/10/16",
          "ID": "<instrument_2_ID>",
          "Value": "98.34211667",
          "Name": "<instrument_2_name>"
        }
      ]
    }

Compute analytics for multiple instruments

Returns the value for the specified analytics for all of the specified instruments using a given scenario, for a specific date, and for specific time steps. If no analytics are specified, the theoretical price is returned.

POST /v2/simulate

Request

Query Parameters

  • Set to CSV, BIN, or JSON (default)

  • Specify a three-letter currency code for reporting purposes.

Form Parameters

  • Within an id-list structure, specify one or more pairs of id and type for each instrument that you want to simulate. type is one of ric, sedol, or isin. id is the ID of the instrument as it specified for the type.

  • Analytics

    Allowable values: [Price,Clean Price,Dirty Price,Value,Exposure,Yield,Profit and Loss,Return,Adjusted Duration,Effective Duration,Macaulay Duration,Monetary Duration,Convexity,Effective Convexity,Monetary Convexity,Implied Spread,Delta,Rho,Gamma,Theta,Vega]

  • The name of a predefined scenario set that is provided by IBM.

  • Specify days (triggers) using an array of numbers. Corresponds to a distinct point in time at which the problem is measured and computed. The value may be either 30 (in 30 days) or 0 (current time). If timestep is not specified, the default is 0.

  • Specify a date in YYYY-MM-DD format.

  • curl --request POST --url https://us-south.sia.cloud.ibm.com/v2/simulate  --header 'Content-Type: application/json' --header 'Authorization-api-key:REPLACE_KEY_VALUE' --header 'Authorization-instance-id:REPLACE_UUID_VALUE' -d '{ "id-list":[{"id":"IBM", "type":"ric"},{"type":"ric","id":"IBMA172012500"}, { "id": "US59022CAJ27", "type":"isin" }],  
      "analytics" : "Dirty Price,Clean Price, Effective Duration",  
      "ibm-scenario-set-name" : "IBM_EquityIndexShifts_AllCurves",
      "valuation-date" : "2018-08-01",   
      "format" : "csv",
      "simulation-days" : "0,6,13,18,30"                   
      }'
  • var XMLHttpRequest = require("xmlhttprequest").XMLHttpRequest;
    var request = new XMLHttpRequest()
    request.open("POST","https://us-south.sia.cloud.ibm.com/v2/simulate")
    request.setRequestHeader("enctype", "string")
    request.setRequestHeader("accept", "application/json")
    request.setRequestHeader("content-type", "multipart/form-data")   
    request.setRequestHeader("Authorization-api-key", "REPLACE_KEY_VALUE")
    request.setRequestHeader("Authorization-instance-id", "REPLACE_UUID_VALUE")              
    data = {
        'id-list': [ {'id':'US4592001014','type':'ISIN'}, {'id':'US44932HAA14','type':'ISIN'} ],
        'analytics': ['Dirty Price','Clean Price','Effective Duration'],
        'ibm-scenario-set-name': "IBM_EquityIndexShifts_AllCurves",
        'valuation-date': "2018-08-01",
        'format': "json",
        'simulation-days': "0,6,13,30"
        }
    request.send(JSON.stringify(data))
    request.onload = () =>console.log(request.responseText) 
    
  • import requests
    import json
    headers = {
        'content-type': "application/json",
        'Authorization-api-key': <REPLACE_KEY_VALUE>
        'Authorization-instance-id': <REPLACE_UUID_VALUE>
        }
    payload = {
        'id-list': [ {'id':'US4592001014','type':'ISIN'}, {'id':'US44932HAA14','type':'ISIN'} ],
        'analytics': ['Dirty Price','Clean Price','Effective Duration'],
        'ibm-scenario-set-name': "IBM_EquityIndexShifts_AllCurves",
        'valuation-date': "2018-08-01",
        'format': "json",
        'simulation-days': "0,6,13,30"
        }
    url = 'https://us-south.sia.cloud.ibm.com/v2/simulate/'
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    print(response.text)
    

Response

Status Code

  • Success. Returns results for each valid instrument ID and the value for each specified analytic. Additional analytics specified in the request body are also returned in the result.

  • The request format is wrong.

  • The request is not authenticated.

  • The requested method is not allowed.

  • An internal error has occured.

Example responses
  • {
      "results": [
        {
          "Simulation Date": "2018/10/16",
          "ID": "<instrument_1_ID>",
          "Name": "<instrument_1_Name>",
          "Scenario Name": "Shifts to all equity indexes",
          "Simulation Days": "Day 0",
          "Currency": "USD",
          "Clean Price": "123.21",
          "Dirty Price": "123.45",
          "Effective Duration": "0"
        },
        {
          "Simulation Date": "2018/10/16",
          "ID": "<instrument_1_ID>",
          "Name": "<instrument_1_Name>",
          "Scenario Name": "Shifts to all equity indexes",
          "Simulation Days": "Day 6",
          "Currency": "USD",
          "Clean Price": "123.32",
          "Dirty Price": "123.56",
          "Effective Duration": "0"
        },
        {
          "Simulation Date": "2018/10/16",
          "ID": "<instrument_1_ID>",
          "Name": "<instrument_1_Name>",
          "Scenario Name": "Shifts to all equity indexes",
          "Simulation Days": "Day 13",
          "Currency": "USD",
          "Clean Price": "123.45",
          "Dirty Price": "123.67",
          "Effective Duration": "0"
        }
      ]
    }