> For the complete documentation index, see [llms.txt](https://docs.ensuro.co/ensuro-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ensuro.co/ensuro-docs/offchain-apis/api-reference/dynamic-pricing-api.md).

# Pricing API

You should have received a partner-specific URL and credentials to use this API. If you didn't, please contact our support team to set up the required services and credentials.

## OPTIONS /example

> Get information about this instance

```json
{"openapi":"3.1.1","info":{"title":"ensuro-policy-quote - OpenAPI 2.0","version":"0.0.2"},"servers":[{"url":"/api/v0"}],"security":[],"paths":{"/example":{"options":{"summary":"Get information about this instance","operationId":"example-options","responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionsResponse"}}}}}}}},"components":{"schemas":{"OptionsResponse":{"type":"object","properties":{"risk_module":{"type":"string"},"signer":{"type":"string"},"decimals":{"type":"integer"},"topic":{"type":"string"}}}}}}
```

## POST /example/quote

> Create a new quote

```json
{"openapi":"3.1.1","info":{"title":"ensuro-policy-quote - OpenAPI 2.0","version":"0.0.2"},"servers":[{"url":"/api/v0"}],"security":[{"api_key_header":[]}],"components":{"securitySchemes":{"api_key_header":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"Quote":{"type":"object","properties":{"quote_id":{"description":"Quote unique identifier, used across Ensuro's APIs","type":"string"},"data_hash":{"description":"Hash that uniquely identifies this policy","type":"string"},"loss_prob":{"description":"Loss probability for the policy, 0 < loss_prob < 1","type":"string"},"premium":{"description":"The premium that must be sent to the contract. If null send MAX_UINT256","type":"string"},"bucket_id":{"description":"[optional] Pricing bucket id, only if the riskmodule is a SignedBucketRiskModule","type":"string"},"signature":{"$ref":"#/components/schemas/Signature"},"valid_until":{"description":"Quote expiration as seconds since epoch","type":"integer"}}},"Signature":{"type":"object","properties":{"hash":{"type":"string"},"r":{"type":"string"},"vs":{"type":"string"}}},"QuoteRequest":{"type":"object","properties":{"data":{"type":"object"},"expiration":{"type":"string","format":"date-time"},"payout":{"type":"string"}}}}},"paths":{"/example/quote":{"post":{"summary":"Create a new quote","operationId":"example-quote-post","parameters":[{"schema":{"type":"boolean"},"description":"Unsigned","in":"query","name":"unsigned","required":false,"allowEmptyValue":true}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Invalid input"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"description":"Quote parameters","required":true}}}}}
```

## POST /example/new-policy

> Create a new policy

```json
{"openapi":"3.1.1","info":{"title":"ensuro-policy-quote - OpenAPI 2.0","version":"0.0.2"},"servers":[{"url":"/api/v0"}],"security":[{"api_key_header":[]}],"components":{"securitySchemes":{"api_key_header":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"Quote":{"type":"object","properties":{"quote_id":{"description":"Quote unique identifier, used across Ensuro's APIs","type":"string"},"data_hash":{"description":"Hash that uniquely identifies this policy","type":"string"},"loss_prob":{"description":"Loss probability for the policy, 0 < loss_prob < 1","type":"string"},"premium":{"description":"The premium that must be sent to the contract. If null send MAX_UINT256","type":"string"},"bucket_id":{"description":"[optional] Pricing bucket id, only if the riskmodule is a SignedBucketRiskModule","type":"string"},"signature":{"$ref":"#/components/schemas/Signature"},"valid_until":{"description":"Quote expiration as seconds since epoch","type":"integer"}}},"Signature":{"type":"object","properties":{"hash":{"type":"string"},"r":{"type":"string"},"vs":{"type":"string"}}},"QuoteRequest":{"type":"object","properties":{"data":{"type":"object"},"expiration":{"type":"string","format":"date-time"},"payout":{"type":"string"}}}}},"paths":{"/example/new-policy":{"post":{"summary":"Create a new policy","operationId":"example-new-policy-post","parameters":[{"schema":{"type":"string","pattern":"0x[0-9a-f]{130}"},"description":"EIP-191 signature of the body digest (SHA256 of the body, without leading '0x'). The signature must be made\nby an authorized signer. Signature format: r+s+v in hexadecimal. Example:\n\"0xc9a9d2e9ebf6a9930705c4517ff7ae6aa91a4799df8f87189488e1f1396080c76cbeb698c047af21ee94d2c5bb89f72a56fb70ac58f1c2b7245e9d2b400c243f1b\"\n\nThis is the preferred signing method. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-EIP191-Signature","required":false},{"schema":{"type":"string","pattern":"[0-9a-f]{64}"},"description":"HMAC-SHA256 signature of the body, using the shared secret provided. The signature must be in hexadecimal,\nwithout including the leading \"0x\", for example:\n\"41deed7140512b0d351a588d05bff44dfdc58a6a038b47edf4f5e944dd1185d6\" will be the signature for body\n'{\"foo\":\"bar\"}' and secret 'topsecret'.\n\nThis method is not recommended, use X-EIP191-Signature whenever possible. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-Ensuro-Signature","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Invalid input"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}},"description":"Policy parameters","required":true}}}}}
```

## POST /example/resolve-policy

> Resolve a policy

```json
{"openapi":"3.1.1","info":{"title":"ensuro-policy-quote - OpenAPI 2.0","version":"0.0.2"},"servers":[{"url":"/api/v0"}],"security":[{"api_key_header":[]}],"components":{"securitySchemes":{"api_key_header":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"ResolutionResponse":{"type":"object","properties":{"status":{"type":"string"}}},"ResolutionRequest":{"type":"object","properties":{"ensuro_id":{"type":"string"},"payout":{"type":"string"}}}}},"paths":{"/example/resolve-policy":{"post":{"summary":"Resolve a policy","operationId":"example-resolve-policy-post","parameters":[{"schema":{"type":"string","pattern":"0x[0-9a-f]{130}"},"description":"EIP-191 signature of the body digest (SHA256 of the body, without leading '0x'). The signature must be made\nby an authorized signer. Signature format: r+s+v in hexadecimal. Example:\n\"0xc9a9d2e9ebf6a9930705c4517ff7ae6aa91a4799df8f87189488e1f1396080c76cbeb698c047af21ee94d2c5bb89f72a56fb70ac58f1c2b7245e9d2b400c243f1b\"\n\nThis is the preferred signing method. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-EIP191-Signature","required":false},{"schema":{"type":"string","pattern":"[0-9a-f]{64}"},"description":"HMAC-SHA256 signature of the body, using the shared secret provided. The signature must be in hexadecimal,\nwithout including the leading \"0x\", for example:\n\"41deed7140512b0d351a588d05bff44dfdc58a6a038b47edf4f5e944dd1185d6\" will be the signature for body\n'{\"foo\":\"bar\"}' and secret 'topsecret'.\n\nThis method is not recommended, use X-EIP191-Signature whenever possible. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-Ensuro-Signature","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionResponse"}}}},"400":{"description":"Invalid input"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolutionRequest"}}},"description":"Policy resolution","required":true}}}}}
```

## POST /example/replace-policy

> Replace a policy

```json
{"openapi":"3.1.1","info":{"title":"ensuro-policy-quote - OpenAPI 2.0","version":"0.0.2"},"servers":[{"url":"/api/v0"}],"security":[{"api_key_header":[]}],"components":{"securitySchemes":{"api_key_header":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"Quote":{"type":"object","properties":{"quote_id":{"description":"Quote unique identifier, used across Ensuro's APIs","type":"string"},"data_hash":{"description":"Hash that uniquely identifies this policy","type":"string"},"loss_prob":{"description":"Loss probability for the policy, 0 < loss_prob < 1","type":"string"},"premium":{"description":"The premium that must be sent to the contract. If null send MAX_UINT256","type":"string"},"bucket_id":{"description":"[optional] Pricing bucket id, only if the riskmodule is a SignedBucketRiskModule","type":"string"},"signature":{"$ref":"#/components/schemas/Signature"},"valid_until":{"description":"Quote expiration as seconds since epoch","type":"integer"}}},"Signature":{"type":"object","properties":{"hash":{"type":"string"},"r":{"type":"string"},"vs":{"type":"string"}}},"ReplacementRequest":{"allOf":[{"$ref":"#/components/schemas/QuoteRequest"},{"type":"object","required":["old_ensuro_id"],"properties":{"old_ensuro_id":{"type":"string"}}}]},"QuoteRequest":{"type":"object","properties":{"data":{"type":"object"},"expiration":{"type":"string","format":"date-time"},"payout":{"type":"string"}}}}},"paths":{"/example/replace-policy":{"post":{"summary":"Replace a policy","operationId":"example-replace-policy-post","parameters":[{"schema":{"type":"string","pattern":"0x[0-9a-f]{130}"},"description":"EIP-191 signature of the body digest (SHA256 of the body, without leading '0x'). The signature must be made\nby an authorized signer. Signature format: r+s+v in hexadecimal. Example:\n\"0xc9a9d2e9ebf6a9930705c4517ff7ae6aa91a4799df8f87189488e1f1396080c76cbeb698c047af21ee94d2c5bb89f72a56fb70ac58f1c2b7245e9d2b400c243f1b\"\n\nThis is the preferred signing method. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-EIP191-Signature","required":false},{"schema":{"type":"string","pattern":"[0-9a-f]{64}"},"description":"HMAC-SHA256 signature of the body, using the shared secret provided. The signature must be in hexadecimal,\nwithout including the leading \"0x\", for example:\n\"41deed7140512b0d351a588d05bff44dfdc58a6a038b47edf4f5e944dd1185d6\" will be the signature for body\n'{\"foo\":\"bar\"}' and secret 'topsecret'.\n\nThis method is not recommended, use X-EIP191-Signature whenever possible. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-Ensuro-Signature","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Invalid input"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplacementRequest"}}},"description":"Replacement parameters","required":true}}}}}
```

## POST /example/cancel-policy

> Cancel a policy

```json
{"openapi":"3.1.1","info":{"title":"ensuro-policy-quote - OpenAPI 2.0","version":"0.0.2"},"servers":[{"url":"/api/v0"}],"security":[{"api_key_header":[]}],"components":{"securitySchemes":{"api_key_header":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"CancelPolicyResponse":{"type":"object","properties":{"ensuro_id":{"type":"string"},"refunds":{"$ref":"#/components/schemas/CancelPolicyRefunds"},"signature":{"$ref":"#/components/schemas/Signature"}}},"CancelPolicyRefunds":{"type":"object","properties":{"pure_premium":{"type":"string"},"jr_coc":{"type":"string"},"sr_coc":{"type":"string"}}},"Signature":{"type":"object","properties":{"hash":{"type":"string"},"r":{"type":"string"},"vs":{"type":"string"}}},"CancelPolicyRequest":{"type":"object","required":["ensuro_id"],"properties":{"ensuro_id":{"description":"The Ensuro policy ID to cancel","type":"string"}}}}},"paths":{"/example/cancel-policy":{"post":{"summary":"Cancel a policy","operationId":"example-cancel-policy-post","parameters":[{"schema":{"type":"string","pattern":"0x[0-9a-f]{130}"},"description":"EIP-191 signature of the body digest (SHA256 of the body, without leading '0x'). The signature must be made\nby an authorized signer. Signature format: r+s+v in hexadecimal. Example:\n\"0xc9a9d2e9ebf6a9930705c4517ff7ae6aa91a4799df8f87189488e1f1396080c76cbeb698c047af21ee94d2c5bb89f72a56fb70ac58f1c2b7245e9d2b400c243f1b\"\n\nThis is the preferred signing method. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-EIP191-Signature","required":false},{"schema":{"type":"string","pattern":"[0-9a-f]{64}"},"description":"HMAC-SHA256 signature of the body, using the shared secret provided. The signature must be in hexadecimal,\nwithout including the leading \"0x\", for example:\n\"41deed7140512b0d351a588d05bff44dfdc58a6a038b47edf4f5e944dd1185d6\" will be the signature for body\n'{\"foo\":\"bar\"}' and secret 'topsecret'.\n\nThis method is not recommended, use X-EIP191-Signature whenever possible. Only one of X-EIP191-Signature or X-Ensuro-Signature must be provided.\n","in":"header","name":"X-Ensuro-Signature","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPolicyResponse"}}}},"400":{"description":"Invalid input"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPolicyRequest"}}},"description":"Policy cancellation parameters","required":true}}}}}
```

### Signatures

For policy creation, resolution, replacement and cancellation the body of the request must be signed.

There's two options available for signing:

* Symmetric: a shared secret will be provided and it has to be used to compute an hmac digest. The digest must be sent in the `X-Ensuro-Signature` of the request.
* Asymmetric: An authorized ethereum account is used to sign the body of the message. This method is safer because only the partner has access to the private key and it does not need to be sent over the internet ever. The signature is computed following the [EIP191](https://eips.ethereum.org/EIPS/eip-191) standard. It must be sent in the `X-EIP191-Signature` header of the request.

Only one of the methods must be used, and "Asymmetric" is the preferred one.

See [our samples repository](https://github.com/ensuro/ensuro-samples-js#webhooks-for-creation-and-resolution) for a js example of how to use each one.