Integration Guide — KalyRails

The concept

Nothing changes for your users or your app

KalyRails exposes a standard JSON-RPC endpoint — the same interface used by every Ethereum-compatible service in the world. If your team has ever called a REST API, you can integrate with KalyRails.

Your backend becomes the bridge between your users and the blockchain. When a user initiates a transfer, your server calls our RPC, and the transaction is recorded on your private ZK chain. The user never knows blockchain is involved.

You can integrate using any language — JavaScript, Python, Java, Go, PHP, Ruby. If it can make an HTTP request, it can talk to KalyRails.

What you need

01

Your RPC endpoint URL (we provide this)

02

Operator signing key (we generate and secure this together)

03

An HTTP client in your backend (you already have one)

Average integration time

1–3 days

Step by step

Connecting your backend

01

Connect with your operator wallet

You operate one custodial signing wallet on your KalyRails chain — nothing more. Your users have no wallets, no addresses, no keys. User balances and history live inside the mobile money smart contract, keyed by your existing user IDs from your own database.

// Load your operator signing wallet (secure it like any API secret)
const { ethers } = require('ethers');

const provider = new ethers.JsonRpcProvider(
  'https://your-chain.kalyrails.io/rpc'  // We provide this
);

const operatorWallet = new ethers.Wallet(
  process.env.KALYRAILS_OPERATOR_KEY,
  provider
);

// Connect to the mobile money contract (address provided at onboarding)
const mobileMoney = new ethers.Contract(
  MOBILE_MONEY_CONTRACT,
  abi,
  operatorWallet
);
      

02

Submit transfers by user ID

When a user initiates a transfer, your backend calls the mobile money contract directly with the sender and recipient's user IDs from your own database. The contract validates limits, deducts a KUSD fee to your revenue treasury, and records the transfer immutably — all in one transaction signed by your operator wallet.

async function sendTransfer(fromUserId, toUserId, amountMinorUnits) {
  // Call the custodial transfer function.
  // The operator wallet is the only signer — your user IDs are the arguments.
  const tx = await mobileMoney.transfer(
    fromUserId,     // your internal user ID (uint256)
    toUserId,       // your internal user ID (uint256)
    amountMinorUnits // amount in smallest unit (e.g. cents)
  );
  const receipt = await tx.wait();

  // Store the on-chain hash as immutable proof of the transfer
  return {
    txHash: receipt.hash,
    blockNumber: receipt.blockNumber,
    feeCollected: receipt.logs /* KUSDFee event */
  };
}

// In your existing transfer endpoint:
app.post('/transfer', async (req, res) => {
  const { fromUserId, toUserId, amount } = req.body;
  const proof = await sendTransfer(fromUserId, toUserId, amount);
  await db.saveTransferProof(req.body.transferRef, proof.txHash);
  res.json({ success: true, proof });
});
      

03

Query balances and history by user ID

User balances live inside the mobile money contract as a mapping from your user ID to a balance. Read them directly with a view call, or use the block explorer's API for richer queries and regulator-ready audit trails.

// Check a user's balance directly on-chain
const balance = await mobileMoney.balanceOf(userId);

// Or use the Explorer API for transaction history by user ID
const history = await fetch(
  `https://explorer.kalyrails.io/api/user/${userId}/transfers`
);
const txns = await history.json();

// Display in your app — users see their normal transaction list
txns.items.forEach(tx => {
  renderTransaction({
    amount: tx.amount,
    counterparty: resolveUserName(tx.counterpartyUserId),
    date: tx.timestamp,
    status: tx.confirmed ? 'complete' : 'pending',
    blockchainProof: tx.txHash  // For regulator-verifiable audit
  });
});
      

Compatibility

Works with any backend stack

KalyRails uses the standard Ethereum JSON-RPC interface. Every major language has libraries ready to go.

JS

JavaScript / Node.js

ethers.js, web3.js, viem

PY

Python

web3.py, brownie

☞

Java / Kotlin

web3j

GO

Go

go-ethereum (geth)

PH

PHP

web3.php

🔸

Any language

Raw HTTP/JSON-RPC calls

What you get

Every integration includes

Pre-built smart contracts

Mobile money transfer contracts, agent commission contracts, merchant settlement contracts — battle-tested and auditable. Handles 80% of use cases out of the box. Custom contracts available for Growth and Enterprise plans.

SDK and code examples

Ready-to-use code samples in JavaScript, Python, and Java showing exactly how to map users, submit transfers, query balances, and handle events. Copy, paste, adapt to your stack.

Testnet environment

A full staging chain where you can test your integration without affecting production. Same API, same contracts, same behavior — but with test tokens so nothing real is at risk.

Integration support

Our engineering team walks you through the integration. We review your code, answer questions, and help debug. Most integrations go from first API call to production in 1-3 days.

Common questions

Integration FAQ

Do we need blockchain developers on our team?

No. If your team can make HTTP API calls, they can integrate with KalyRails. The RPC interface is identical to any REST API. Smart contract development and blockchain infrastructure is entirely handled by us.

What if our backend is in a language you didn't list?

KalyRails uses standard JSON-RPC over HTTP. If your language can send an HTTP POST request with a JSON body, it can talk to KalyRails. No special libraries required.

Can we run alongside our existing database?

Absolutely. Most clients keep their existing database for user management, KYC, app state, etc. and add KalyRails as the settlement layer. Your database remains your source of truth for app logic — the blockchain adds immutable proof of every financial transaction.

What happens if the ZK chain goes down?

Your app continues working. You can queue transactions locally and submit them when the chain recovers. All data is also stored in a managed PostgreSQL database with automated backups. Our SLA guarantees 99.9% uptime on Growth and Enterprise plans.

How do USSD-based apps integrate?

USSD interfaces talk to your backend server, which talks to KalyRails via JSON-RPC. The integration point is your backend — not the user's phone. Whether your users are on a smartphone app, USSD, or even SMS, the blockchain integration is the same.

Connect your existing backend in hours, not months