Authentication

Generate SG connect token

For connecting to the external API, you first need to get a SG Connect token that will authenticate you in the SG ecosystem. For that you must call SG Connect server with your secret and client id formatted correctly. You need to send your credentials separated by a “:” (ex: “secret:client_id”) and encoded as a base64 string. Then add the result in the headers, under the “Authorization” property preceded by “Basic” (see curl example).

You also need to specify the grant type and the scope. The scope will determine the rights that will be granted to you (example: read, write) and the grant type is the way your credential will flow in the SG ecosystem. For connecting to the external API, you must specify the grant type as ”client credentials” and the scope as “openid profile api.sgmarkets-execution-structured-products.v1”.

Please refer to SG Markets Apis / Authentication for further information.

	using (var client = new HttpClient()) { 
	// Format client and secret id
	var result = Convert.ToBase64String(Encoding.UTF8.GetBytes("client_id:secret_id"));
							
	//Define Headers
	client.DefaultRequestHeaders.Accept.Clear();
	client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
	client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", result);

	//Prepare Request Body
	var requestData = new List<KeyValuePair<string, string>> {
		new KeyValuePair<string, string>("grant_type", "client_credentials")
	};
	var requestBody = new FormUrlEncodedContent(requestData);

	//Request Token
	var request = await client.PostAsync("https://sso.sgmarkets.com/sgconnect/oauth2/access_token?grant_type=client_credentials&
										scope=openid profile api.sgmarkets-execution-structured-products.v1", requestBody);
	}

	import requests

	access_token_endpoint = "https://sso.sgmarkets.com/sgconnect/oauth2/access_token"

	lient_id = "..."
	client_secret = "..."
	scopes = ["openid", "profile", "api.sgmarkets-execution-structured-products.v1"]

	response = requests.post(access_token_endpoint,
	verify=False,
	auth=(client_id, client_secret),
	data={'grant_type': 'client_credentials', 'scope': ' '.join(scopes)})

	if response.ok:
	print(response.json()["access_token"])

	curl -Method POST -Headers @{"Accept"="application/json";" 
	Authorization"="Basic MhBhRzc1ZjAtNDlmMi0ON2FhLVhlODQtYmC2YmNlYWQxMzI5OjFkYWxpZXszYzRkaWo0aWg3ZTg3ZG04OTY2NThr"} 
	'https://sso.sgmarkets.com/sgconnect/oauth2/access_token? 
	grant_type=client_credentials&scope=openid profile api.sgmarkets-execution-structured-products.v1'

SG Connect token Refresh

You must refresh the SG Connect token after a certain period of time, the validity period of the token is given under the “expires_in” property of the response given by SG Connect server, this unit is expressed in seconds.

Primary market API end points

• POST /api/v1/quotes creates an indicative quote based on the variation parameters sent. The response contains the quote id, the status of the operation, the requested solve, and a list of errors if there are any.
• GET /api/v1/quote/{quoteId} retrieves the quote details by ID. When status is Accepted the response will contain only the basic information. When status is Quoted, all details are available. The previous call returns either "Status": "Accepted" and some basic information, or "Status": "Quoted" and much more data.

  Examples:

  {
      "Data": {
          "QuoteId": "SGM-00000484601",
          "SolveFor": "KiBarrier",
          "SolveResult": 0,
          "Mifid2": {
          "PgRequired": "no",
          "KidId": "KID-AST-9aW6Yggykd",
          "KidRequired": "yes"
          }
      },
      "Status": "Accepted"
  }                                    
  

  {
      "Data": {
          "QuoteId": "SGM-00000484601",
          "SolveFor": "KiBarrier",
          "SolveResult": 88.43,
          "Quote": {
          "Wrapper": "Note",
          "IssuePricePercent": 100,
          "RemunerationMode": "Upfront",
          "NotionalType": "Currency",
          "NotionalAmount": 1000000,
          "UpfrontFee": 2.5,
          [...]
          },
      [...],
      "Status": "Quoted",
      "RepriceLink": "https://demo.sgmarkets.com/sp/#/quote/SGM-00000484601",
      "TradeAuthorizationStatus": "Denied"
  }
  

• POST /api/v1/tradable-quotes creates a tradable quote based on the variation parameters sent. Response contains the quote id, the status of the operation, the requested solve, and a list of errors if any.
• POST /api/v1/tradable-quotes/{tradableQuoteId}/execution allows to execute a tradable quote when it has been granted a trading authorization. The authorization status is available in the GET /api/v1/quote/{quoteId} call. First, you will get ACK the Accepted status.

  {
      "Status": "Accepted",
      QuoteId": "SGM-00000484601"
                          
  }                                    
  

  Then, call the route GET /api/v1/quote/{quoteId} to get more information about the status of the execution request. If the deal is traded, the system should return the status Traded.

  {
      [...],
      "Status": "Traded",
      "RepriceLink": "https://demo.sgmarkets.com/sp/#/quote/SGM-00000484601",
      "TradeAuthorizationStatus": "Granted"
  }                           
  

• GET /api/v1/trade/{quoteId} retrieves the trade details by quote id. When the deal is booked, the status will be set to Booked

  {
      "QuoteId": "SGM-00000484601",
      "Status": "Booked",
      "Isin": "isin code",
      "CreatedOn": "2021-12-28 09:38:28Z",
      "TradeDate": "2021-12-28",
      "Maturity": "2025-01-07",
      "Currency": "EUR",
      "User": "your email",
      "Notional": 1000000,
      "SettlementPrice": 100,
      "UpfrontFee": 2.5,
      "Wrapper": "Note",
      "ProductFamily": "Autocall"
  }                         
  

• GET/api/v1/quote-request/{quoteId} retrieves the json quote request linked to a specific quote id. You can price a quote via the interface and retieves via this end point its equivalent JSON request to price via the API.
• GET /api/v1/termsheet/{quoteId}/{language} downloads the indicative termsheet related to the quote being priced. The response is a PDF file.
• POST /api/v1/custodians retrieves the custodians codes and labels. The codes are mandatory to submit tradable quotes.
• GET /api/v1/underlying-universe gives you the lists the underlyings granted to you, grouped by asset class.

Basic rules for indicative quotes

When requesting for an indicative quote with regulation, meaning with Mifid2section, you have many use cases:

• If only the KID is required by default in the system: the KID document will be generated
• If only the Target Market is required by default in the system, the Target Market document will be generated
• If both KID and Target Markets are required by default in the system: the KID and the Target Market documents will be generated
• If both KID and Target Markets are not required by default in the system, it is possible to force the documents generation

When requesting for an indicative quote without regulation, meaning without Mifid2 section the KID and the Target Market will not be generated even if they are configured as required in the system.

Basic rules for tradable quotes

When requesting for a tradable quote

• If only the KID is mandatory in the system, the KID document will be generated anyway whatever we add or not the Mifid2 section in the JSON template.
• If only the Target Market is mandatory, the Target Market document will be generated anyway whatever you add or not the Mifid2 section in the JSON template.
• If the KID and/or the Target Market documents are not mandatory and not configured as required in the system, but they are needed, you can force the documents generation.
• If the KID and/or the Target Marketdocuments are not mandatory and the document generation is not forced, it will not be generated.

To force the KID generation, you should add the additionalKidLanguages tag under the mifid2 section.

{
    [...],
    "mifid2": {
        "distributionCountries": [
          "France","UnitedKingdom"
        ],
        "additionalKidLanguages": [
          "German","Dutch"
        ]
      },
    [...]
}                                                

To force Target Market generation, you should add the tag ForceTargetMarket under the mifid2 section:

{
    [...],
    "mifid2": {
        [...],
        "forceTargetMarket": true
      },
    [...]               
} 

The values of available KID and Distribution Countries languages are available from the Schemas section from the swagger: API Swagger

DistributionCountry: string
    Enum
        [ Andorra, UnitedArabEmirates, Argentina, Austria, Belgium, Bahrain, Bahamas, Bermuda, Bolivia, Brazil, Switzerland, 
        Chile, Colombia, CostaRica, CaymanIslands, Germany, Ecuador, Spain, Finland, France, UnitedKingdom, Guernsey, 
        Guatemala, HongKong, Honduras, Ireland, Israel, Italy, Jersey, Luxembourg, Monaco, Mexico, Netherlands, 
        Panama, Peru, Portugal, RussianFederation, SaudiArabia, Singapore, ElSalvador, Sweden, Uruguay, BritishVirginIslands, 
        Dubai, SouthAfrica ]

KidLanguage: string
    Enum
        [ Finnish, Dutch, English, French, German, Italian, Portuguese, Spanish, Swedish ]

Trade workflow

• call the route POST /api/v1/custodians It’s the end point to get the custodians. The codes should be used to fill in the deal notional split section when submitting a tradable quote.

      {
          "Custodians": [
            {
              "Code": "custodian num id 1",
              "Label": "Custodian name 1",
              "DisabledInSecondaryMarket": true
            },
            [...],
            {
              "Code": "custodian num id n",
              "Label": "Custodian name n"
            }
          ]
      }            
  

• call the route POST /api/v1/tradable-quotes/{tradableQuoteId}/execution It’s the end point to submit a tradable quote. When the quote is summitted, a quote id sent back.

      {
          "Status": "OK",
          "QuoteId": "SGM-00000484722",
          "Errors": [],
          "RepriceLink": "https://demo.sgmarkets.com/sp/#/quote/SGM-00000484722"
      }                     
  

• call the route GET /api/v1/quote/{quoteId} The quote id should be used to get the quote results. When the quote has been traded, the trade authorization may be granted ("TradeAuthorizationStatus": "Granted"). youn can then trade.

  {
      [...],
      "Status": "Quoted",
      "RepriceLink": "https://demo.sgmarkets.com/sp/#/quote/SGM-00000484722",
      "TradeAuthorizationStatus": "Granted"
  }                               
  

• call the route POST /api/v1/tradable-quotes/{tradableQuoteId}/execution It’s the end point to use to trade once the trade authorization has been granted. you get an accept acknowlegment or a rejection. Here below the ACK when the trade execution has been accepted.

  {
      "Status": "Accepted",
      "QuoteId": "SGM-00000484722"
  }                     
  

• When the trade has been done, the Get quote end point may be used to get the "Status": "Traded"
• call the route GET /api/v1/quote/{quoteId}

  {
      "QuoteId": "SGM-00000484722",
      "Status": "Booked",
      "Isin": "your isin code",
      "CreatedOn": "2021-12-28 14:30:01Z",
      "TradeDate": "2021-12-28",
      "Maturity": "2025-01-07",
      "Currency": "EUR",
      "User": "your email",
      "Notional": 1000000,
      "SettlementPrice": 100,
      "UpfrontFee": 2.5,
      "Wrapper": "Note",
      "ProductFamily": "Autocall"
  }
  

FAQ

keyboard_arrow_right How to customize the schedule?

• Add the below section to the JSON template to customize recallThreshold and recallCoupon for periods 2 and 3.

{
    [...],
    "scheduleCustomization": [
        {
        "periodId": 2,
        "recallThreshold": 99,
        "recallCoupon": 3
        },
        {
        "periodId": 4,
        "recallThreshold": 98,
        "recallCoupon": 7
        }
    ],
    [...]                                     
}

• As a result, the schedule will be customized as below:

keyboard_arrow_right How to perform a step-down schedule?

• Add these lines to the JSON template to:

• As a result, the schedule will be customized as below:

keyboard_arrow_right How to generate KID document for an indicative quote?

When requesting for an indicative quote with regulation, meaning with Mifid2 section, you have many use cases:

• If only the KID is mandatory:

KID document will be generated with the defaulted languages configured in the system and there is no need to explicitly add the AdditionalKidLanguages tag.

Example:
For a specific client, only KID is mandatory in the system and it is configured as required with these three languages by default: English, Italian and French. In the JSON template, you will only need to add the Mifid2 section as shown below:

As an output you will have the three KID documents generated with the three defaulted Languages English, Italian and French:

• If an additional KID language should be added, the tag AdditionalKidLanguages should be used

Example:


For a specific client, only KID is mandatory in the system, and it is configured as required with these three languages by default: English, Italian and French.

If an additional KID language needs to be added, let’s say German, use the below tag.



In the JSON template you will need to add the Mifid2 section as shown below:



As an output you will have 4 KID documents generated with four Languages English, Italian, French and German.

keyboard_arrow_right How to force Target Market document generation for an indicative quote?

If the Target Market document is needed and not configured as required in the system, we will need to force the generation, to do so the tag ForceTargetMarket must be added to the Mifid2 section as shown below:

As output you will have 4 KID documents generated with four Languages English, Italian, French and German plus the Target Market document:

keyboard_arrow_right How to download regulation documents?

For indicative and tradable quotes, call the route with the SGM IDGET /api/v1/quote/{quoteId} to get the quote details, the regulation documents are available in the the Mifid2 section.

Below an example of an output:

keyboard_arrow_right What are the mandatory fields for an indicative and tradable quote?

Mandatory fields for an indicative quote:

1. ProductType
2. ProductSubtype
3. Wrapper
4. Currency
5. Underlying
6. SolvingMode

Mandatory fields for a tradable quote:

1. ProductType
2. ProductSubtype
3. Wrapper
4. Currency
5. Underlying
6. DealSplit
7. SolvingMode

keyboard_arrow_right What are the reading and writing limits per end point?

post:/api/v1/tradable-quotes/*/execution: Writing capacity is 3 per minute

get:/api/v1/underlying-universe*: Reading capacity is 1 per minute

post:/api/v1/tradable-quotes*: Writing capacity is 3 per minute

post:/api/v1/custodians*: Reading capacity is 1 per minute

get:/api/v1/termsheet/*: Reading capacity is 6 per minute

get:/api/v1/quote/*: Reading capacity is 6 per minute

post:/api/v1/quotes*: Writing capacity is 3 per minute

get:/api/v1/trade/*: Reading capacity is 6 per minute

If the limit is reached, The request will be rejected and the HTTP error code 429 (Too many requests) will be returned

keyboard_arrow_right How to get the term-sheet?

Use the route GET /api/v1/termsheet/{quoteId}/{language}, The response is a PDF file.

Entry data: The quote ID and the choosen language, today 2 options are available (English and French)

Result: Coded termsheet, it should be then converted from Base64 to PDF.

keyboard_arrow_right How to add trade allocations in case of a tradable quote request?

1. Add the tag DealSplit to the JSON file as shown below.

2. The Your first custodian is the BDR returned when calling the route: POST /api/v1/custodians

Please see the example below:

Entry data:

Response:

keyboard_arrow_right Are primary and secondary markets RFQ supported in the API?

We support the Secondary Market via the API. The documentation is comming soon. You can find out the secondary API end point via the API Swagger

Example of JSON requests

Autocalls

Product Subtype	Wrapper	Solve for	Json
Athena/Apollon	Note	Upfront fee
Athena/Apollon	Note	Strike
Athena/Apollon	Note	Recall coupon
Athena/Apollon	Note	Recall threshold
Athena/Apollon	Note	KI threshold