Canton request-response oracle

Real-time Reference Rates & Indices on Canton

This guide provides step-by-step instructions for creating market data requests to Kaiko using the Kaiko oracle on the Canton blockchain. You can see our full range of Reference Rates and Multi-Asset Indices available on Canton here.

Overview

The Kaiko oracle enables secure, paid/licensed requests for real-time Reference Rates and Multi-Asset Indices through the Canton blockchain. The system follows the standard request-response oracle workflow:

1. Prepare request parameters: Format the Kaiko-specific payload.

2. Retrieve contracts: Get the current Amulet rules and open mining round contracts.

3. Exercise a contract choice: Submit a transaction to create a data request.

The oracle processes the request off-chain (settling payment via Amulets) and posts the Kaiko market data response back on-ledger.

Prerequisites

Required information

You need the following information before starting:

• Canton participant endpoint: URL of your Canton participant JSON API

• Canton authentication token: Valid token for API access

• Consumer party ID: Your party identifier in Canton (e.g., Consumer::1220...)

• RequestFactory contract ID: Contract ID for the request factory

• DSO party ID: DSO party identifier

• Data provider details (provider-dependent): Data request payload (stringified JSON)

• Amulet contract ID: An Amulet contract to fund payment

• Payment locked amount: Amount to lock for the request

Environment setup

Ensure you have:

• A Canton node connected to the same domain as the oracle node

• The Prepaid Oracle DAR uploaded to your Canton node

• Sufficient Amulet balance for the request

Creating a Data Request

Prepare provider request parameters

The Kaiko oracle accepts requests for one or more tickers (real-time reference rates and indices).

Input model (Kaiko)

You must prepare the payload as valid JSON and then stringify it for the Canton command.

• rates (Required): Array of Kaiko tickers.

Example tickers:

• KK_RFR_BTCUSD

• KK_RFR_CCUSD

• EGLXRT

JSON
{
"rates": ["KK_RFR_BTCUSD", "EGLXRT"]
}

Stringidied payload

When sending the request to Canton, pass the stringified version (quotes escaped):

"{\"rates\":[\"KK_RFR_BTCUSD\",\"EGLXRT\"]}"

Submit the request creation transaction

Make a POST request to Canton to exercise the CreateRequest choice.

Request Endpoint:

POST

{PARTICIPANT_NODE_JSON_API_URL}/v2/commands/submit-and-wait-for-transaction-tree

Headers

• Authorization: Bearer {CANTON_TOKEN}

• Content-Type: application/json

Request body example:

{
"actAs": ["{YOUR_CONSUMER_PARTY}"],
"commandId": "kaiko-request-1",
"commands": [
{
"actAs": ["{YOUR_CONSUMER_PARTY}"],
"commandId": "kaiko-request-1",
"ExerciseCommand": {
"contractId": "{REQUEST_FACTORY_CONTRACT_ID}",
"templateId":
"{PACKAGE_ID}:PrepaidOracle.RequestFactory:RequestFactory",
"choice": "CreateRequest",
"choiceArgument": {
"dso": "{DSO_PARTY}",
"amuletRulesCid": "{AMULET_RULES_CONTRACT_ID}",
"openRoundCid": "{OPEN_ROUND_CONTRACT_ID}",
"inputs": [
{
"tag": "InputAmulet",
"value": "{YOUR_AMULET_CONTRACT_ID}"
}
],
"dataRequest": "{\"rates\":[\"KK_RFR_BTCUSD\",\"EGLXRT\"]}",
"lockedAmount": {PAYMENT_LOCKED_AMOUNT}
}
}
}
],
"disclosedContracts": [
{
"templateId": "{AMULET_PACKAGE_ID}:Splice.AmuletRules:AmuletRules",
"contractId": "{AMULET_RULES_CONTRACT_ID}",
"synchronizerId": "{GLOBAL_DOMAIN_SYNCHRONIZER_ID}",
"createdEventBlob": "{AMULET_RULES_DISCLOSED_BLOB}"
},
{
"templateId": "{AMULET_PACKAGE_ID}:Splice.Round:OpenMiningRound",
"contractId": "{OPEN_ROUND_CONTRACT_ID}",
"synchronizerId": "{GLOBAL_DOMAIN_SYNCHRONIZER_ID}",
"createdEventBlob": "{OPEN_ROUND_DISCLOSED_BLOB}"
}
]
}

Reading the FilledRequest

Once the oracle processes your request, it archives the pending request and creates a FilledRequest contract containing the Kaiko data.

Query for FilledRequest

Use the active contracts endpoint to retrieve the result.

Request endpoint

POST

{PARTICIPANT_NODE_JSON_API_URL}/v2/state/active-contracts

Request body filter: filter for template

{PACKAGE_ID}:PrepaidOracle.Request:FilledRequest.

Kaiko response structure

In the resulting FilledRequest contract, the responseData field contains the stringified Kaiko output.

Response data model (Kaiko)

The response is a JSON object keyed by rate id(s), containing the returned value(s).

Example (conceptual):

{
"KK_RFR_BTCUSD": "...",
"EGLXRT": "..."
}

Example FilledRequest content

{
"oracle": "{ORACLE_PARTY}",
"consumer": "{YOUR_CONSUMER_PARTY}",
"requestData": "{\"rates\":[\"KK_RFR_BTCUSD\",\"EGLXRT\"]}",
"responseData": "{\"KK_RFR_BTCUSD\":\"...\",\"EGLXRT\":\"...\"}",
"serviceAmountCharged": "1.0000000000"
}

Troubleshooting

Invalid JSON structure

• Cause: The dataRequest string was not properly escaped or contained invalid JSON.

• Solution: Ensure your stringified JSON does not contain unescaped quotes, stray backslashes, or newlines.

Unknown/unsupported rate identifier

• Cause: One or more requested rate identifiers are not available to your entitlement, are misspelled, or are not supported by the oracle.

• Solution: Validate the exact rate tickers (e.g., KK_RFR_BTCUSD), confirm access/entitlements, and retry with supported identifiers.