Introduction

We provide RESTful APIs to our partners for easier integration. The actions that can be performed through our APIs are:

• Create a new policy

• Resolve an existing policy

• Get the pricing and optionally obtain a signature to create a policy onchain

• Query policy details

Some of these operations are asynchronous, so partners can also set up to receive callback notifications with the results of the operations.

Quickstart Guide

Integrating with our APIs is really simple. The first step is on our end, setting up the necessary services and credentials. Once that's done you'll get four things:

• A URL for the pricing API

• An API key

• A signing secret

• The address of your risk module

You'll need all of these to properly integrate.

Your first call to our service: pricing a policy

On your first call you'll just need the URL and the API key. This endpoint will price a policy without creating or signing anything:

Shell

curl --request POST \
  --url "$URL/quote?unsigned" \
  --header 'Content-Type: application/application/json' \
  --header 'X-API-Key: $API_KEY' \
  --data '{"payout": "100.98","expiration": "2024-12-31T21:36:07.211025Z","data": {"pricing": "general"}}'

Python

import requests
import json

URL = "..."
API_KEY = "secret"

data = {"pricing": "general"}

response = requests.post(
    f"{URL}/quote",
    headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
    params={"unsigned": True},
    data=json.dumps({"payout": "100.98", "expiration": "2024-12-31T21:36:07.211025Z", "data": data}),
)

print(json.dumps(response.json(), indent=2))

NodeJS

const axios = require("axios");

const URL = "...";
const API_KEY = "secret";

async function printQuote() {
  const data = {
    pricing: "Bedwin",
    blissid: "c5629d49-cd6f-4ccc-8a58-b46637988e51",
  };

  const response = await axios({
    method: "post",
    url: `${URL}/quote`,
    headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
    params: { unsigned: true },
    data: { payout: "100.98", expiration: "2024-12-31T21:36:07.211025Z", data },
  });

  console.log(response.data);
}

printQuote()
  .then(() => process.exit(0))
  .catch((e) => {
    console.error(e);
    process.exit(1);
  });

Notice that the specific parameters that you need to send on the call will depend on the pricing structure and settings, you should've received more specific instructions about what to include in the data object.

Some parameters will always be required:

• payout is the policy's max payout in USD.

• expiration is the policy's expiration. The example uses a UTC timestamp, but you can pick the timezone that's better for your business.

The response will look something like this:

{
  bucket_id: 'general',
  contract_address: '0x0d175CB042dd6997ac37588954Fc5A7b8bab5615',
  data_hash: '0x469428e566ecf36d57bc13cd75446eec1cf36c2b89ddc2d4e610280ed607ae03',
  ensuro_id: '5921344226728579096291186784487329498769731945547014779449079388463409114627',
  expiration: 1735680967,
  loss_prob: '0.0436',
  premium: null,
  premium_details: {
    ensuro_commission: '0.692791',
    jr_coc: '2.130666',
    minimum_premium: '9.822071',
    pure: '5.50341',
    sr_coc: '1.495204'
  },
  quote_id: 'c5629d49-cd6f-4ccc-8a58-b46637988e51',
  valid_until: 1716311048
}

You can check the API reference for a detailed description of each, but the most important ones are:

• ensuro_id: this will be the policy ID on our system, it identifies each policy univocally across our protocol.

• loss_prob: this is the loss probability assigned to the policy. When testing out your integration you should validate that this loss probability matches the pricing set forth for the product.

• premium_details : this is a breakdown of the premium as per the current pricing.

If you remove the unsigned parameter from the call to /quote you will get an additional field with the signature for the quote. With this signature you can call our smart contract to create a policy.

Creating a policy

Although you can obtain signed quotes and use those to create policies on the blockchain, it's more practical to just create the policies directly by calling our API.

To do this, you'll have to sign the body of your request using an HMAC signature.

Shell

URL="..."
API_KEY="secret"
SIGN_SECRET="T0pS3cret"


body='{"payout": "100.98", "expiration": "2024-12-31T14:21:55+00:00", "data": {"pricing": "general"}}'
signature=$(echo -n "$body" | openssl dgst -sha256 -hmac "$SIGN_SECRET" | sed 's/^.*= //')

curl --request POST \
  --url "$URL/new-policy" \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $API_KEY" \
  --header "X-Ensuro-Signature: $signature" \
  --data "$body"

Python

import requests
import json
import hmac
from hashlib import sha256

URL = "..."
API_KEY = "secret"
SIGN_SECRET = "T0pS3cret"

data = {"pricing": "general"}

raw_request = json.dumps(
    {
        "payout": "100.98",
        "expiration": "2024-12-31T21:36:07.211025Z",
        "data": data,
    }
).encode("utf-8")
digest = hmac.new(bytes(SIGN_SECRET, "utf-8"), msg=raw_request, digestmod=sha256).hexdigest()
response = requests.post(
    f"{URL}/new-policy",
    headers={
        "X-API-Key": API_KEY,
        "X-Ensuro-Signature": digest,
        "Content-Type": "application/json",
    },
    data=raw_request,
)

print(json.dumps(response.json(), indent=2))

NodeJS

const axios = require("axios");
const { createHmac } = require("crypto");

const URL = "...";
const API_KEY = "secret";
const SIGN_SECRET = "T0pS3cret";

async function createNewPolicy() {
  const data = { pricing: "general" };
  const body = {
    payout: "100.98",
    expiration: "2024-12-31T21:36:07.211025Z",
    data,
  };
  const jsonBody = JSON.stringify(body);

  const signature = createHmac("sha256", SIGN_SECRET)
    .update(jsonBody)
    .digest("hex");

  const response = await axios({
    method: "post",
    url: `${URL}/new-policy`,
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
      "X-Ensuro-Signature": signature,
    },
    data: jsonBody,
  });

  console.log(response.data);
}

createNewPolicy()
  .then(() => process.exit(0))
  .catch((e) => {
    console.error(e);
    process.exit(1);
  });

The returned object will be the same as when calling /quote. You should take note of the ensuro_id because you'll need it to resolve policies later on.

Resolving a policy

You can resolve a policy with any payout up to the max payout established on policy creation. This transfers the payout to the policy owner and releases the rest of the locked capital for use in other policies.

Here as well you'll need to sign the body of the request.

Shell

URL="..."
API_KEY="secret"
SIGN_SECRET="T0pS3cret"


body='{"payout": "100.98", "ensuro_id": "5921344226728579096291186784487329498769731945547014779449079388463409114627"}'
signature=$(echo -n "$body" | openssl dgst -sha256 -hmac "$SIGN_SECRET" | sed 's/^.*= //')

curl --request POST \
  --url "$URL/resolve-policy" \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $API_KEY" \
  --header "X-Ensuro-Signature: $signature" \
  --data "$body"

Python

import requests
import json
import hmac
from hashlib import sha256

URL = "..."
API_KEY = "secret"
SIGN_SECRET = "T0pS3cret"


raw_request = json.dumps(
    {
        "payout": "100.98",
        "ensuro_id": "5921344226728579096291186784487329498769731945547014779449079388463409114627",
    }
).encode("utf-8")
digest = hmac.new(bytes(SIGN_SECRET, "utf-8"), msg=raw_request, digestmod=sha256).hexdigest()
response = requests.post(
    f"{URL}/resolve-policy",
    headers={
        "X-API-Key": API_KEY,
        "X-Ensuro-Signature": digest,
        "Content-Type": "application/json",
    },
    data=raw_request,
)

print(json.dumps(response.json(), indent=2))

NodeJS

const axios = require("axios");
const { createHmac } = require("crypto");

const URL = "...";
const API_KEY = "secret";
const SIGN_SECRET = "T0pS3cret";

async function resolvePolicy() {
  const body = {
    payout: "100.98",
    ensuro_id: "5921344226728579096291186784487329498769731945547014779449079388463409114627",
  };
  const jsonBody = JSON.stringify(body);

  const signature = createHmac("sha256", SIGN_SECRET)
    .update(jsonBody)
    .digest("hex");

  const response = await axios({
    method: "post",
    url: `${URL}/resolve-policy`,
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
      "X-Ensuro-Signature": signature,
    },
    data: jsonBody,
  });

  console.log(response.data);
}

resolvePolicy()
  .then(() => process.exit(0))
  .catch((e) => {
    console.error(e);
    process.exit(1);
  });

You should get a 200 response with this json content:

{"status":"QUEUED"}

And the policy should get resolved on the blockchain shortly afterward.

As you can see, all operations done through our API are asynchronous. You should set up your own HTTP endpoint where you can receive notifications about the status of the operations.