Developer Tools
BUILD AN AGENT THAT PAYS WITH KAELUM
Your agent can find products from KAELUM merchants, quote the KAE price with the merchant's discount, and start a checkout for its user. The user always approves the payment themselves, with a passkey for larger amounts. K.A.T.E. governs the rails. Your user governs the spend.
1. Discover live products and merchants
Read-only and public. Returns live, in-stock products with KAELUM pricing, and the merchants that accept KAE.
GET https://kaelum.app/functions/kaelumDiscover?q=hoodie&limit=20&offset=0 GET https://kaelum.app/functions/kaelumDiscover?category=<category id from a product's category_id>
2. Quote the price in KAE
Read-only. Returns the merchant's discount and the KAE required for an amount, exactly as checkout will charge it.
GET https://kaelum.app/functions/kaelumQuote?siteKey=<merchant site key>&amount=56.00
3. Start a checkout for your user
Creates a checkout session and returns a link. Send your user to checkout_url; they review and approve the payment there. Your agent never completes a payment itself.
POST https://kaelum.app/functions/createPlatformCheckoutSession
Content-Type: application/json
x-kaelum-agent-key: kag_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{
"siteKey": "<merchant site key>",
"amount": "56.00",
"orderId": "your-order-123",
"itemDescription": "Dragon Mosaic Slip-on Canvas Shoes | Size 9",
"sourceUrl": "https://merchant.example/product/123",
"idempotency_key": "your-unique-request-id"
}
200 OK
{
"id": "klm_sess_...",
"checkout_url": "https://kaelum.app/checkout/klm_sess_...",
"expires_at": 1790000000,
"agent_verified": true
}Use a unique idempotency_key for each purchase so a retried request never creates a second checkout.
Get verified
KAELUM registers agent platforms and issues each one an agent key. When your server sends the key in the x-kaelum-agent-key header, the checkout shows your agent's name with Verified by KAELUM, and the payment is recorded as made through a verified agent. Requests without a key still work, but show as Not verified by KAELUM, and merchants or KAELUM may require extra confirmation for them.
To register, email info@kaelumtechnologies.com with your agent's name, your company, a contact email and your website.
Looking after your key
- Keep the key on your servers. Never put it in a browser, app bundle or public repository.
- If it may have leaked, tell us and we will revoke it and issue a new one. Revoked keys show as unverified straight away.
- Only send the key on requests your agent makes for a real user who asked it to buy something.
How KAELUM keeps users in control
- Every payment is approved by the user on KAELUM, with a passkey at or above the user's threshold.
- Users can pause all agent buying at any time, and KAELUM can pause agent purchasing platform-wide.
- Every agent payment is sealed in KAELUM's OBSIGNIA ledger.
- KAE is a closed-loop commerce currency fixed at £0.20 a unit. It is not a cryptocurrency and not an investment.
Building for merchants instead? See KAELUM for merchants.