Komainu API (1.4.0)

The Komainu API is a RESTful API that you can integrate with your system.

Get in touch with your Account Manager to access the Komainu API.

You can download our Postman API Collection here (collection, environment)

• Our platform API URL: https://api.komainu.io
• Test environment URL: https://api-demo.komainu.io

Note: The postman collection includes a sample script to generate a message signature using unencrypted private key. If you encrypt the private key, you will need to either update the script accordingly or use unencrypted private key.

All of our API endpoints require authentication. First, you need to generate a Private Key / Public Key pair.

• Elliptic curve
  • SECP256R1
• Private key encoding
  • encoding PEM
• Private key format
  • PKCS8
• Public key encoding
  • Base64

You can do this by using the following command:

from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec

import base64

def generate_keys(passphrase: str):
    if not passphrase:
        raise ValueError("Passphrase is required for key generation")
    private_key = ec.generate_private_key(ec.SECP256R1(), default_backend())

    private_key_bytes = private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.BestAvailableEncryption(passphrase.encode("utf-8")),
    )

    print("\n *** Private Key (encrypted) *** \n")

    private_key_pem = private_key_bytes.decode("utf-8")
    print(f"\nIn PKCS8 (PEM):\n{private_key_pem}")

    private_key_base64 = base64.b64encode(private_key_bytes).decode("utf-8")
    print(f"\nIn PKCS8 (Base64):\n{private_key_base64}")

    private_key_hex = private_key_bytes.hex()
    print(f"\nIn PKCS8 (Hex):\n{private_key_hex}")
    
    print("\n\n *** Private Key (unencrypted) *** \n")

    # Load the encrypted private key and decrypt it
    loaded_private_key = serialization.load_pem_private_key(
        private_key_bytes,
        password=passphrase.encode("utf-8"),
        backend=default_backend()
    )
    
    # Get the unencrypted version
    unencrypted_private_key_bytes = loaded_private_key.private_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PrivateFormat.PKCS8,
        encryption_algorithm=serialization.NoEncryption(),
    )
    unencrypted_private_key_pem = unencrypted_private_key_bytes.decode("utf-8")
    print(f"\nIn PKCS8 (PEM):\n{unencrypted_private_key_pem}")
    
    unencrypted_private_key_base64 = base64.b64encode(unencrypted_private_key_bytes).decode("utf-8")
    print(f"\nIn PKCS8 (Base64):\n{unencrypted_private_key_base64}")
    
    unencrypted_private_key_hex = unencrypted_private_key_bytes.hex()
    print(f"\nIn PKCS8 (Hex):\n{unencrypted_private_key_hex}")

    print("\n\n *** Public Key *** \n")

    public_key = private_key.public_key()
    public_key_bytes = public_key.public_bytes(
        encoding=serialization.Encoding.PEM,
        format=serialization.PublicFormat.SubjectPublicKeyInfo,
    )
    public_key_pem = public_key_bytes.decode("utf-8")
    print(f"\nIn PEM:\n{public_key_pem}")

    public_key_base64 = base64.b64encode(public_key_bytes).decode("utf-8")
    print(f"\nIn Base64:\n{public_key_base64}")

    public_key_hex = public_key_bytes.hex()
    print(f"\nIn Hex:\n{public_key_hex}")

    print("\n\n *** For API User Registration, please use the following public key *** \n")
    print(f"\nIn Base64:\n{public_key_base64}")


# Get passphrase from user
def get_passphrase():
    passphrase = input("Enter passphrase: ")
    return passphrase

passphrase = get_passphrase()
generate_keys(passphrase)

The private key is used to sign the request. Then, you need to submit your public key via Komainu Portal while registering your API User (or email to an account manager). Once your API User is fully approved, you can generate a secret from the same screen.

1. Retrieve an access token by sending a POST request to the /v1/auth/token endpoint with your username and password in the payload.

curl --request POST https://api.komainu.io/v1/auth/token \
  --header 'content-type: application/json' \
  --data '{"api_user": "***","api_secret": "***"}'

The response will contain an access_token, which you will use in all subsequent requests.

{
  "access_token": "ey***.***.***",
  "expires_in": 600,
  "token_type": "Bearer"
}

2. Sign your request by adding the following headers:

• Authorization: bearer token from the previous step
• X-Timestamp: the current timestamp in milliseconds
• X-Signature: the signature of the request

The signature is a base64 encoded string of the ES256 signature of the following string:

canonical_string = <host>,<method>,<path>,<base64(sha256(body))>,<base64(sha256(token))>,<timestamp>

where:

• <host> is the host of the API (api.komainu.io or api-demo.komainu.io)
• <method> is the HTTP method of the request in lower case (get, post, put, patch, delete)
• <path> is the path of the request with the query string (e.g. /transactions/1?wallet_id=3)
• <base64(sha256(body))> is 'sha256=' followed by the base64 encoded sha256 hash of the request body (if the request has no body, use an empty string)
• <base64(sha256(token))> is 'sha256=' followed by the base64 encoded sha256 hash of the bearer token
• <timestamp> is the value of the X-Timestamp header, milliseconds in unix time

Then, sign the canonical string with your private key and encode the hex-encoded hash in base64. Make sure to use the unencrypted private key. i.e. base64(hmac_es256(canonical_string))

The completed input for the x-signature should look similar to:

api.komainu.io,post,/v1/custody/transactions,sha256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=,sha256=In7qwVHNt4SeKwD8qSzJCTlmmabBcKWREgMQ3APEXDo=,1699870783112

and the X-Signature (output) should look like:

w9vsJx+bezboTilm6h2qXEng9UClkU/ntP/8o/SjRzEirbnUO7RRBEUN7ilLDAl69ZwevzJTOaUI0ws8Rh+F4UH26Ipq+QRhQgIgxHNNIek1y6zbMyrladM9+tgtz73HOhbuXBrdi7BGOBLv4bv9kSsSukA8C2ZVxqYxEV8LyfiVGsY06wSRaUgwGk3bBu7FuUK2fdwyQbZqam9ArJa+98tmOgJBY4/Md551bgN7gjDuBLxHplUKiFXx9XbhqC6pwVtiSU0UwvembDIGutxa5PMXowuF6WddJWMEddIY8B7rB0OyNnev4t2hbCQEz5tyk0idDV7IRiIcDNi7Ng39eQ==

This should be sent in the X-Signature header along with X-Timestamp header.

The API supports idempotency for POST requests. To use this feature, include the X-Idempotency-Key header in your request. The value of this header should be a unique identifier for the request. If the request is repeated with the same idempotency key, the response will be the same as the original request.

The following rate limits are applied to the API User by default. Please contact your Account Manager if you need to increase the rate limits.

• 300 requests per 5 minutes for all endpoints regardless of the response
• 5 requests per 20 seconds for each of post endpoints
• Unusually high number of requests on Authentication endpoint may be blocked by brute force protection
• High number of concurrent open requests may be dropped

1. Create a request

To initiate a transaction, you need to create a request with the type CREATE_TRANSACTION to this endpoint:

• POST /v1/custody/requests endpoint.

Generally, the transaction payload will be created after calling these endpoints:

• GET /v1/custody/wallets to get the wallet_id
• POST /v1/custody/transactions/estimate-fee to get the estimated fee

Note that the estimate fee endpoint requires the API User to have Initiate Transaction permission. Upon successful creation, the request will be in the status CREATED.

2. Wait and validate the request

Komainu will validate the submitted request. During this process,

• GET /v1/custody/requests/{request_id} will return the status CREATED.
• GET /v1/custody/requests/{request_id}/challenge will return 404 not found.

Once the request is successfully validated in the system,

• GET /v1/custody/requests/{request_id} will return the status PENDING.
• GET /v1/custody/requests/{request_id}/challenge will return a challenge, which is base64 encoded string of the request stored in the vault

You will then need to decode the challenge and validate it with the request data.

In case the request is invalid for some reason, the request will be in the status BLOCKED.

3. Confirm or cancel the request

If the challenge is valid, you can confirm or cancel the request. Use the API User's private key to sign the challenge and generate jws (jws consists of three parts, concatenated by period: the JWS Header, the JWS Payload, and the JWS Signature, where each part is base64url-encoded).

import jwt

def sign_challenge(challenge: bytes, private_key_hex: str) -> str:
  private_key_bytes = bytes.fromhex(private_key_hex)
  challenge_data_bytes = jwt.utils.base64url_decode(challenge)
  jws = jwt.PyJWS()
  jws: str = jws.encode(challenge_data_bytes, private_key_bytes, algorithm="ES256")
  return jws

To confirm the request, you need to sign the challenge with your private key and send it to

• POST /v1/custody/requests/{request_id}/confirm
• The request will be in the status PENDING_FOR_APPROVAL where approvers can approve the request.

To cancel the request, you need to sign the challenge with your private key and send it to

• POST /v1/custody/requests/{request_id}/cancel
• The request will be in the status CANCELLED. No further action can be taken to this request.

1. Get a request

To approve a request, you need to get the request by Id from this endpoint:

• GET /v1/custody/requests/{request_id}

If this is the request for the API User to approve, get the challenge code by calling this endpoint:

• GET /v1/custody/requests/{request_id}/challenge

This will return a challenge, which is base64 encoded string of the request stored in the vault. You will then need to decode the challenge and validate it with the request data. If you are not the approver, this endpoint will return 404 not found.

2. Approve or reject the request

If the challenge is valid, you can approve or reject the request. Use the API User's private key to sign the challenge and generate jws (jws consists of three parts, concatenated by period: the JWS Header, the JWS Payload, and the JWS Signature, where each part is base64url-encoded).

import jwt

def sign_challenge(challenge: bytes, private_key_hex: str) -> str:
  private_key_bytes = bytes.fromhex(private_key_hex)
  challenge_data_bytes = jwt.utils.base64url_decode(challenge)
  jws = jwt.PyJWS()
  jws: str = jws.encode(challenge_data_bytes, private_key_bytes, algorithm="ES256")
  return jws

To approve the request, you need to sign the challenge with your private key and send it to

• POST /v1/custody/requests/{request_id}/approve

To reject the request, you need to sign the challenge with your private key and send it to

• POST /v1/custody/requests/{request_id}/reject
• The request will be in the status REJECTED. No further action can be taken to this request.

A request that has not been completed within the expiry will be automatically discarded.

You can receive notifcations from Komainu via webhook or email on transactions and requests events.

Each API User can register a Webhook URL to receive notifications. It receives relevant events for the API User based on the permission. The webhook URL and secret are registered in Komainu Portal while registering the API User (or email to an account manager if you do not have access to the portal).

You will receive a POST call to the registered URL with the event data in the body.

{"event_type": "REQUEST_CREATED", "entity": "REQUEST", "entity_id": "dbe727e0-6a58-434d-9253-f085545dc7e9"}

The list of events are as follows in a table:

The webhook request is sent with the following headers:

• X-Komainu-Signature: the signature of the request
• X-Komainu-Timestamp: the timestamp of the request

The signature can be validated by the secret submitted in the webhook registration.

SECRET = "mysecret"
USER = "api_user"

@app.route("/", methods=["POST"])
def webhook():
    signature = request.headers["X-Komainu-Signature"]
    timestamp = request.headers["X-Komainu-Timestamp"]

    if time.time() - int(timestamp) > 5 * 60:
        raise ValueError("message is too old, possible replay attack")

    to_sign = timestamp.encode() + b"." + request.data
    computed_signature = hmac.new(SECRET.encode(), to_sign, "sha256").hexdigest()
    if not hmac.compare_digest(signature, computed_signature):
        raise ValueError("signature mismatch")

Komainu also supports email notifications for new transactions (inbound / outbound). Please contact your account manager for the details.

Release Date: 2025-07-18

New Features

• Added balance webhook event

API Enhancements

• Updated pagenation parameters for page and page_size

Release Date: 2025-07-04

New Features

• Added daily staking rewards reporting
• Added transaction webhook events

From this endpoint, you can call the following Requests API.

From this endpoint, you can call the following Wallets API.

From this endpoint, you can call the following Transactions API.

From this endpoint, you can call the following Whitelist API.

From this endpoint, you can call the following User API.

From this endpoint, you can call the following Asset API.

From this endpoint, you can call the following Account API.

From this endpoint, you can call the following Workspace API.

From this endpoint, you can call the following Ethereum Staking API.

From this endpoint, you can call the following Solana Staking API.

From this endpoint, you can call the following Staking Rewards API.