Quoting and Trading API

With this API you can quote and trade structured products and OTC derivatives. This guide explains the key features of the API and the data structures used.

The basic quoting/trading flow

This API can be used to quote and trade products in flows where Vontobel is either a client (sends QuoteRequests) or a service (consumes QuoteRequests). These two flows require two separate infrastructure configurations, but in either case the flow follows the same principles:

The client sends a QuoteRequest
The service immediately responds with a QuoteRequestAck acknowledging the reciept of the quote request
Once the service computes/solves the price, it sends back a QuoteResult to the client
The client checks QuoteResult.Status to see if the quoting was successful
Optionally, the client can follow up with a TradeRequest using the QuoteRequest.Id.Request identifier
The service immediately responds with a TradeRequestAck acknowledging the receipt of the trade request
Once the service fully confirms the trade, it will publish a TradeResult to the client
The client checks the TradeResult.Status to confirm the trade was successfully confirmed

The client can optionally specify the id -> clientRequest identifier. The service doesn't need/use this identifier, but it will carry it throughout the entire flow, helping the client to correlate its own messages. On the other hand, the service will generate a unique id -> request identifier right after the first response (QuoteResultAck) to uniquely identify the flow - this identifier must to be attached to each following message for the given flow and will be used by the service to correlate messages related to a specific quote/trade request.

The quote request

The quote request has three major parts:

id to provide a client reference id
quotingParameters to specify certain parameters, such as the seeking parameter
product to define the product parameters

Reference: see swagger reference

{
  "id":{
    "clientRequest": "5e5b6e02-5ca2-40be-9ab7-47982102d03a"
  },
  "quotingParameters": {
    "seekingParameter": "Price",
    "quoteType": "Tradeable",
    "clientDirection": "Short"
  },
  "product": {
    "$type": "VanillaOption",
    "currency": "CHF",
    "optionType": "Put",
    "initialFixingDate": { "offset": "0B" },
    "initialPaymentDate": { "offset": "2B" },
    "finalFixingDate": { "offset": "12M" },
    "finalPaymentDate": { "offset": "2B" },
    "underlyings": [
      { "id": { "bloomberg": "SMI Index" } }
    ],
    "initialFixingType": "Close",
    "settlementType": "Cash",
    "price": { 
      "type": "Percent"
    },
    "strike": { "percent": 1.0 },
    "size": {
      "notional": 100000,
      "denomination": 500
    }
  }
}

product is a polymorphic field, meaning that based on the $type field it can take different shapes (consult the OpenAPI schema for more details). For example, the $type: VanillaOption product will have a different set of fields than the $type: CallableReverseConvertible - the latter will have call and coupon schedules.

note

This polymorphic type approach will manifest itself in more places, for example the call/coupon schedule fields are also polymorphic - schedules can be parametric where the client just specifies a call/coupon frequency and the service will generate the dates automatically, or fixed in which case the client has to provide a fixed call/coupon schedule with all the call/coupon dates listed.

Another important aspect of the API is date handling. The client is allowed to use date offsets or explicit dates:

  // using offsets
  "product": {
     ...
    "initialFixingDate": { "offset": "0B" },
    "initialPaymentDate": { "offset": "2B" },
    "finalFixingDate": { "offset": "12M" },
    "finalPaymentDate": { "offset": "2B" },
     ...
  }

  // using explicit dates
  "product": {
     ...
    "initialFixingDate": { "date": "2025-04-01" },
    "initialPaymentDate": { "date": "2025-04-03" },
    "finalFixingDate": { "date": "2026-04-01" },
    "finalPaymentDate": { "date": "2026-04-03" },
     ...
  }

When Vontobel plays the role of the quoting/trading service, it supports offset dates, but 3rd party services using this API are not required to support offset dates, as Vontobel will always send explicit dates in the requests/responses.

Offset dates are always converted into explicit dates in QuoteResults. Date generation is based on multiple parameters such as the list of underlyings, the settlement type, currency etc.

Certain fields support both a percent and an absolute input. For example the strike field can be entered as a percent:

"strike": { "percent": 1.0 },

Or as an absolute value:

"strike": { "absolute": 12726.58 },

The actual reference point of a percent value depends on the field. For example, in case of the strike the reference value is the referenceSpot that will be returned in the QuoteResult. If percentage values are used in the output, they will be "expanded" into absolute values in the QuoteResult:

 ...
"strike": {
  "absolute": 12726.58,
  "percent": 1
},
"referenceSpot": 12726.58,
"initialFixingType": "Close",
 ...

Certain values, such as the strike and the barrier level can be specified both on the payoff level and also on the underlying level in the QuoteRequest. The underlying level input has precendence over the payoff level input, and the payoff level input is moved to the underlying level in the QuoteResult to avoid any confusion.

The quote result

The quote result returns practically the same quote request that was sent, except it contains the solution (in this case the price that we solved for) and it expands certain fields. For example, it will expand offset dates into actual fixed dates, set the reference spot used for the calculation, return the actual value of fields that were defaulted because the client didn't specify them.

{
  "status": {
    "status": "Success"
  },
  "id": {
    "Request": "6a90c0b3-5a0d-474d-b543-fcabf26b8cc3",
    "ClientRequest": "5e5b6e02-5ca2-40be-9ab7-47982102d03a"
  },
  "quotingParameters": {
    "seekingParameter": "Price",
    "quoteType": "Tradeable",
    "clientDirection": "Short"
  },
  "product": {
    "$type": "VanillaOption",
    "optionType": "Put",
    "initialFixingDate": { "date": "2025-04-01" },
    "initialPaymentDate": { "date": "2025-04-03" },
    "finalFixingDate": { "date": "2026-04-01" },
    "finalPaymentDate": { "date": "2026-04-07" },
    "underlyings": [
      {
        "id": { "bloomberg": "SMI Index" },
        "strike": {
          "absolute": 12726.58,
          "percent": 1
        },
        "referenceSpot": 12726.58,
        "initialFixingType": "Close",
        "initialFixingDate": {
          "date": "2025-04-01"
        }
      }
    ],
    "isQuanto": false,
    "currency": "CHF",
    "price": {
      "type": "Percent",
      "value": 0.0454
    },
    "size": {
      "notional": 100000,
      "denomination": 500,
      "sharesCalculationType": "DenominationPerStrike"
    },
    "settlementType": "Cash"
  }
}

In terms of schema, the exact same id, quotingParameters and product types are used. Please note the following changes to the product:

If the pricing was successful, the field we solved for (e.g.: Price) is populated now
If offset dates were used in the QuoteRequest, then they are replaced with explicit fixed dates
If percent values were used in the QuoteRequest, they also contain now absolute values
Certain fields, such as the strike were moved under the underlyings
Certain optional fields that were not specified were returned with their default value

The status field contains a top level status value and optionally a list of warning or error messages when the quoting fails.

{
  ...
  "status": {
    "status": "Fail",
    "messages": [
      {
        "message": "Volume CHF 100 is less than minimum 10000 [Code IS-6930-G]",
        "severity": "Error",
        "visibility": "Public"
      }
    ]
  }
  ...
}

The trade request

In order to trade a successful qoute result, the client needs to use the QuoteResult.Id.Request identifier from the quote result.

Reference: see swagger reference

{
  "id": {
    "Request": "6a90c0b3-5a0d-474d-b543-fcabf26b8cc3"
  }
}

The trade result

Upon a successful trade confirmation the service will respond with a TradeResult.

The TradeResult will contain the product from the QuoteResult - it is the exact same product as in the QuoteResult, only added for convenience for clients.

At the moment the only new information in the TradeResult is the ISIN.

{
  "status": {
    "status": "Success"
  },
  "id": {
    "Request": "364f793d-d639-4347-bb8f-2264ad325a47",
    "Simulation": "34581311",
    "Valdet": "3651286477",
    "ISIN": "XF0040490223"
  },
  "product": {
    "$type": "VanillaOption",
    "optionType": "Put",
    "initialFixingDate": { "date": "2025-04-01" },
    "initialPaymentDate": { "date": "2025-04-03" },
    "finalFixingDate": { "date": "2026-04-01" },
    "finalPaymentDate": { "date": "2026-04-07" },
    "underlyings": [
      {
        "id": { "bloomberg": "SMI Index" },
        "strike": {
          "absolute": 12726.58,
          "percent": 1
        },
        "referenceSpot": 12726.58,
        "initialFixingType": "Close",
        "initialFixingDate": {
          "date": "2025-04-01"
        }
      }
    ],
    "isQuanto": false,
    "currency": "CHF",
    "price": {
      "type": "Percent",
      "value": 0.0454
    },
    "size": {
      "notional": 100000,
      "denomination": 500,
      "sharesCalculationType": "DenominationPerStrike"
    },
    "settlementType": "Cash"
  }
}

The basic quoting/trading flow​

The quote request​

The quote result​

The trade request​

The trade result​

The basic quoting/trading flow

The quote request

The quote result

The trade request

The trade result