On-chain intents (preview)

Report the transaction hash of a client-submitted intent

Preview: available on staging (https://staging-execution.kairos.trade); production returns 503 until release.

Only for committed intents with submissionOwner: "client". The hash is a hint: it moves the intent to reconciling and Kairos confirms it from the finalized receipt. A later report can replace a hash that has not been verified; once the intent is confirmed, only the confirmed hash is accepted. Reports are optional — Kairos also finds the transaction on chain.

POST

onchain-intents

{id}

reports

Report the transaction hash of a client-submitted intent

curl --request POST \
  --url https://execution.kairos.trade/v3/onchain-intents/{id}/reports \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Kairos-Partner-Id: <api-key>' \
  --data '
{
  "intentHash": "<string>",
  "transactionHash": "<string>"
}
'

import requests

url = "https://execution.kairos.trade/v3/onchain-intents/{id}/reports"

payload = {
    "intentHash": "<string>",
    "transactionHash": "<string>"
}
headers = {
    "X-Kairos-Partner-Id": "<api-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Kairos-Partner-Id': '<api-key>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({intentHash: '<string>', transactionHash: '<string>'})
};

fetch('https://execution.kairos.trade/v3/onchain-intents/{id}/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://execution.kairos.trade/v3/onchain-intents/{id}/reports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'intentHash' => '<string>',
    'transactionHash' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Kairos-Partner-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://execution.kairos.trade/v3/onchain-intents/{id}/reports"

	payload := strings.NewReader("{\n  \"intentHash\": \"<string>\",\n  \"transactionHash\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Kairos-Partner-Id", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://execution.kairos.trade/v3/onchain-intents/{id}/reports")
  .header("X-Kairos-Partner-Id", "<api-key>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"intentHash\": \"<string>\",\n  \"transactionHash\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://execution.kairos.trade/v3/onchain-intents/{id}/reports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Kairos-Partner-Id"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"intentHash\": \"<string>\",\n  \"transactionHash\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "intent": {
    "terms": {
      "contractVersion": 1,
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "partnerId": "<string>",
      "audience": "<string>",
      "executionRegion": "<string>",
      "signer": "<string>",
      "account": "<string>",
      "chainId": "137",
      "market": "<string>",
      "operation": "split",
      "submissionOwner": "kairos",
      "submissionEndpoint": "<string>",
      "batch": {
        "factory": "<string>",
        "nonce": "<string>",
        "deadline": "2023-11-07T05:31:56Z",
        "calls": [
          {
            "target": "<string>",
            "value": "0",
            "data": "<string>"
          }
        ]
      },
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ],
      "dependencies": [
        {
          "intentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "intentHash": "<string>",
          "account": "<string>",
          "chainId": "137",
          "effects": [
            {
              "token": {
                "kind": "erc20",
                "contract": "<string>"
              },
              "direction": "debit",
              "amountRaw": "<string>"
            }
          ]
        }
      ],
      "maxWalletGasCostRaw": "0",
      "createdAt": "2023-11-07T05:31:56Z",
      "executeBefore": "2023-11-07T05:31:56Z"
    },
    "intentHash": "<string>",
    "status": "needs_signatures",
    "committed": true,
    "dispatchClaimed": true,
    "transactionHash": "<string>",
    "proof": {
      "transactionHash": "<string>",
      "blockHash": "<string>",
      "blockNumber": "<string>",
      "intentHash": "<string>",
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ]
    }
  },
  "consentRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "nativeRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "submission": {
    "endpoint": "<string>",
    "method": "POST",
    "kind": "deposit_wallet_batch",
    "body": {}
  }
}

{
  "error": "unknown or expired action"
}

{
  "error": "sign-in token has expired; run a login action"
}

{
  "error": "API key missing trade:read scope"
}

{
  "error": "on-chain intent not found"
}

{
  "error": "unknown or expired action"
}

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

{
  "error": "rate limit exceeded for this endpoint; retry later"
}

{
  "error": "internal error"
}

{
  "error": "unknown or expired action"
}

Authorizations

X-Kairos-Partner-Id

string

header

required

Wallet API partner id, issued by Kairos together with the partner's base URL. Identifies the partner (tenant) on every /v3 call; sent instead of an API key. Letters, digits and ._:-, at most 64 characters, case-insensitive. A partner id issued for an individual account cannot be sent this way — that account sends its API key triple instead.

Authorization

string

header

required

Wallet sign-in token: SIWE <token>, where <token> is result.token from a login action (exactly one space after SIWE). Proves the wallet on reads of its orders and positions, and on trade plans, fee settlements and on-chain intents. The token is bound to the partner and the environment that issued it and lasts 24 hours; run a new login action to renew it.

Path Parameters

string<uuid>

required

On-chain intent id (intent.terms.id).

Body

application/json

intentHash

string

required

Must equal intent.intentHash.

Pattern: ^0x[0-9a-f]{64}$

transactionHash

string

required

Lowercase 0x + 64 hex.

Pattern: ^0x[0-9a-f]{64}$

Response

The intent, now reconciling (or confirmed).

An on-chain intent with its two signing requests, both eth_signTypedData_v4 by terms.signer on Polygon (params[1] is a JSON string — pass it unchanged):

consentRequest — KairosOnchainIntent typed data binding signer, partnerId, audience, intentId, intentHash, executeBefore. Always required.
nativeRequest — the deposit wallet's Batch authorization over terms.batch. Send it to Kairos when submissionOwner is kairos; keep it for your own submission when client.

Signatures must be plain 65-byte ECDSA (low-s) from the owner key; smart-account signatures are refused.

intent

object

required

Show child attributes

An EIP-1193 request to run through the wallet's provider exactly as given (provider.request({method, params})).

eth_signTypedData_v4: params = [address, typedData] — typedData is a JSON string; pass it unchanged.
personal_sign: params = [hexMessage, address].
wallet_sendCalls (EIP-5792): params = [{version, chainId, from, atomicRequired, calls}]; the wallet pays gas.
eth_sendTransaction: params = [{from, to, data, value, chainId?}]; the wallet pays gas.

Show child attributes

Example:

{
  "method": "personal_sign",
  "params": [
    "0x6b6169726f732e7472616465207761…",
    "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  ]
}

nativeRequest

object

required

An EIP-1193 request to run through the wallet's provider exactly as given (provider.request({method, params})).

eth_signTypedData_v4: params = [address, typedData] — typedData is a JSON string; pass it unchanged.
personal_sign: params = [hexMessage, address].
wallet_sendCalls (EIP-5792): params = [{version, chainId, from, atomicRequired, calls}]; the wallet pays gas.
eth_sendTransaction: params = [{from, to, data, value, chainId?}]; the wallet pays gas.

Show child attributes

Example:

{
  "method": "personal_sign",
  "params": [
    "0x6b6169726f732e7472616465207761…",
    "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  ]
}

submission

object

required

For submissionOwner: client: add "signature": <native signature> to body and POST it to endpoint.

Show child attributes

Report the transaction hash of a client-submitted intent

curl --request POST \
  --url https://execution.kairos.trade/v3/onchain-intents/{id}/reports \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Kairos-Partner-Id: <api-key>' \
  --data '
{
  "intentHash": "<string>",
  "transactionHash": "<string>"
}
'

import requests

url = "https://execution.kairos.trade/v3/onchain-intents/{id}/reports"

payload = {
    "intentHash": "<string>",
    "transactionHash": "<string>"
}
headers = {
    "X-Kairos-Partner-Id": "<api-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Kairos-Partner-Id': '<api-key>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({intentHash: '<string>', transactionHash: '<string>'})
};

fetch('https://execution.kairos.trade/v3/onchain-intents/{id}/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://execution.kairos.trade/v3/onchain-intents/{id}/reports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'intentHash' => '<string>',
    'transactionHash' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Kairos-Partner-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://execution.kairos.trade/v3/onchain-intents/{id}/reports"

	payload := strings.NewReader("{\n  \"intentHash\": \"<string>\",\n  \"transactionHash\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Kairos-Partner-Id", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://execution.kairos.trade/v3/onchain-intents/{id}/reports")
  .header("X-Kairos-Partner-Id", "<api-key>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"intentHash\": \"<string>\",\n  \"transactionHash\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://execution.kairos.trade/v3/onchain-intents/{id}/reports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Kairos-Partner-Id"] = '<api-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"intentHash\": \"<string>\",\n  \"transactionHash\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "intent": {
    "terms": {
      "contractVersion": 1,
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "partnerId": "<string>",
      "audience": "<string>",
      "executionRegion": "<string>",
      "signer": "<string>",
      "account": "<string>",
      "chainId": "137",
      "market": "<string>",
      "operation": "split",
      "submissionOwner": "kairos",
      "submissionEndpoint": "<string>",
      "batch": {
        "factory": "<string>",
        "nonce": "<string>",
        "deadline": "2023-11-07T05:31:56Z",
        "calls": [
          {
            "target": "<string>",
            "value": "0",
            "data": "<string>"
          }
        ]
      },
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ],
      "dependencies": [
        {
          "intentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "intentHash": "<string>",
          "account": "<string>",
          "chainId": "137",
          "effects": [
            {
              "token": {
                "kind": "erc20",
                "contract": "<string>"
              },
              "direction": "debit",
              "amountRaw": "<string>"
            }
          ]
        }
      ],
      "maxWalletGasCostRaw": "0",
      "createdAt": "2023-11-07T05:31:56Z",
      "executeBefore": "2023-11-07T05:31:56Z"
    },
    "intentHash": "<string>",
    "status": "needs_signatures",
    "committed": true,
    "dispatchClaimed": true,
    "transactionHash": "<string>",
    "proof": {
      "transactionHash": "<string>",
      "blockHash": "<string>",
      "blockNumber": "<string>",
      "intentHash": "<string>",
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ]
    }
  },
  "consentRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "nativeRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "submission": {
    "endpoint": "<string>",
    "method": "POST",
    "kind": "deposit_wallet_batch",
    "body": {}
  }
}

{
  "error": "unknown or expired action"
}

{
  "error": "sign-in token has expired; run a login action"
}

{
  "error": "API key missing trade:read scope"
}

{
  "error": "on-chain intent not found"
}

{
  "error": "unknown or expired action"
}

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

{
  "error": "rate limit exceeded for this endpoint; retry later"
}

{
  "error": "internal error"
}

{
  "error": "unknown or expired action"
}

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

Report the transaction hash of a client-submitted intent

Authorizations

Path Parameters

Body

Response