SDK Reference

Integrate Kortana into your backend using our official SDKs for TypeScript, Ruby, Python, Go, PHP, C#, Java and Rust. Every example below shows the exact SDK method and the JSON response object you should expect.

Select Language/Framework:

Active: TypeScript

1. Installation & Setup

TypeScript

npm install @kortana-dev/sdk

import { KortanaClient } from '@kortana-dev/sdk';

const client = new KortanaClient({
  apiKey: 'kt_test_xxx',        // Your API key from the dashboard
  environment: 'testnet',        // 'testnet' or 'mainnet'
});

// Modules available:
// client.wallets    — On-chain DNR transfers & balance
// client.cards      — Virtual card issuance, funding & listing
// client.banking    — NeoBanking customers, accounts, transfers

2. Making Requests

Each example below shows the SDK call, the data fed in, and the exact JSON response from the live API.

Get Wallet Balance

Retrieve the on-chain balance of your merchant hot wallet.

Request — TypeScript

const balance = await client.wallets.getBalance();
console.log(balance.available, balance.currency);

Response

{
  "currency": "DNR",
  "available": "11999999999999999999979000",
  "pending": "0",
  "total": "11999999999999999999979000",
  "usdValue": "24000000.00"
}

Transfer Funds

Send DNR tokens from your hot wallet to any on-chain address.

Request — TypeScript

const tx = await client.wallets.transfer({
  to: '0xf251038d1dB96Ce1a733Ae92247E0A6F400F275E',
  amount: '1000',
  currency: 'DNR'
});
console.log(tx.txHash);

Response

{
  "id": "111bb6c9-b55f-4f6e-bc1c-2dd043f2ac72",
  "type": "send",
  "amount": "1000",
  "currency": "DNR",
  "status": "confirmed",
  "txHash": "0xb9f7ef80f26beadd7040bd1fa58e88f2...",
  "from": "0x3b6dbe334fe6faf71360dbbc74671a0c1c167608",
  "to": "0xf251038d1dB96Ce1a733Ae92247E0A6F400F275E"
}

Issue Virtual Card

Create a new virtual card. The card starts with 0 balance — use the Fund endpoint to load DNR from your blockchain wallet.

Request — TypeScript

const card = await client.cards.create({
  customerId: 'cus_123',
  type: 'virtual',
  currency: 'USD',
  spendLimit: '1000'
});
console.log(card.id, card.last4);

Response

{
  "id": "dcb5d04a-5e99-4b34-89da-944d2a627dc0",
  "customerId": "cus_123",
  "last4": "1331",
  "brand": "kortana",
  "expiryMonth": 9,
  "expiryYear": 2031,
  "status": "active",
  "type": "virtual"
}

Fund Card

Top up a virtual or physical card by transferring DNR from your blockchain wallet. This broadcasts a real on-chain transaction on both testnet and mainnet.

Request — TypeScript

const result = await client.cards.fund(card.id, '100');
console.log(result.newBalanceDnr, result.txHash);

Response

{
  "success": true,
  "data": {
    "id": "dcb5d04a-5e99-4b34-89da-944d2a627dc0",
    "newBalanceDnr": "100.0",
    "txHash": "0x891a8e294cf82aaecf9bfb7464b13222...",
    "status": "funded"
  }
}

List Cards

Retrieve all cards belonging to the merchant.

Request — TypeScript

const cards = await client.cards.list({ limit: 10 });
cards.forEach(c => console.log(c.last4, c.status));

Response

[
  {
    "id": "dcb5d04a-...",
    "last4": "1331",
    "brand": "kortana",
    "status": "active",
    "type": "virtual"
  }
]

Create Customer

Request — TypeScript

const customer = await client.banking.createCustomer({
  name: 'Alice Smith',
  email: 'alice@example.com',
  phone: '+15559876543'
});
console.log(customer.id);

Response

{
  "id": "aecdcdde-323c-45cf-ba3d-92a993215b4c",
  "name": "Alice Smith",
  "email": "alice@example.com",
  "phone": "+15559876543",
  "status": "active"
}

Create Bank Account

Issue a new NeoBanking account with routing and account numbers.

Request — TypeScript

const account = await client.banking.createBankAccount({
  customerId: customer.id,
  bankName: 'Kortana NeoBank',
  accountNumber: '1111222233',
  routingNumber: '098765432',
  accountType: 'checking'
});

Response

{
  "id": "9c3945b6-3816-42d5-b5c9-d86e741aad90",
  "customerId": "aecdcdde-323c-...",
  "bankName": "Kortana NeoBank",
  "accountNumber": "1111222233",
  "routingNumber": "098765432",
  "accountType": "checking",
  "status": "active"
}

Create Transfer

Move fiat funds between two NeoBanking accounts.

Request — TypeScript

const transfer = await client.banking.createTransfer({
  fromAddress: sourceAccount.id,
  toAddress: destAccount.id,
  amount: '500',
  currency: 'USD'
});
console.log(transfer.status); // "completed"

Response

{
  "id": "ccf9c9cc-71bb-4dad-97ba-4616297b1a03",
  "fromAddress": "0b2f4074-8ef6-4b1c-8b75-7c51a1201e55",
  "toAddress": "d1066735-3ef6-4560-aa4d-bf5bf92c54af",
  "amount": "500",
  "currency": "USD",
  "status": "completed",
  "type": "domestic",
  "createdAt": "2026-07-05T06:18:02.525Z",
  "completedAt": "2026-07-05T06:18:02.524Z"
}

Submit KYC documents

Submit customer passport, facial photo, and address documents as base64 images for verification.

Request — TypeScript

const kyc = await client.compliance.submitKyc({
  customerId: 'cus_805e0b0b',
  passport: 'data:image/jpeg;base64,...',
  facialImage: 'data:image/jpeg;base64,...',
  addressDoc: 'data:image/jpeg;base64,...'
});
console.log(kyc.status); // "pending_review"

Response

{
  "success": true,
  "customerId": "805e0b0b-14ab-4672-b57a-f1b6ee7c2572",
  "status": "pending_review",
  "documents": {
    "passportUrl": "https://res.cloudinary.com/fruoak2b/image/upload/v1720162000/kortana/kyc/kortana_kyc_rdpp7.png",
    "facialImageUrl": "https://res.cloudinary.com/fruoak2b/image/upload/v1720162000/kortana/kyc/kortana_kyc_6avf1.png",
    "addressDocUrl": "https://res.cloudinary.com/fruoak2b/image/upload/v1720162000/kortana/kyc/kortana_kyc_1kk0t.png"
  },
  "submittedAt": "2026-07-05T07:46:57.945Z"
}

Apply for Physical Card

Submit details to issue a physical debit card to a neobank customer.

Request — TypeScript

const card = await client.cards.applyPhysical({
  customerId: 'cus_805e0b0b',
  fullName: 'Alice Smith',
  address: '123 Blockchain Way, New York, NY 10001',
  telephone: '+15559876543',
  idNumber: 'BANK-ID-99213'
});
console.log(card.cardNumberMasked);

Response

{
  "success": true,
  "id": "500dc273-fc76-44d7-b702-4e3578b63bd7",
  "customerId": "805e0b0b-14ab-4672-b57a-f1b6ee7c2572",
  "cardholderName": "Alice Smith",
  "cardNumberMasked": "9055 •••• •••• 2200",
  "last4": "2200",
  "brand": "kortana",
  "status": "pending_shipping",
  "type": "physical",
  "shippingAddress": "123 Blockchain Way, New York, NY 10001"
}

Create Escrow Contract

Lock funds inside a secure escrow contract.

Request — TypeScript

const escrow = await client.escrows.create({
  buyerAddress: '0x3b6dbe334fe6faf71360dbbc74671a0c1c167608',
  sellerAddress: '0xf251038d1dB96Ce1a733Ae92247E0A6F400F275E',
  amount: '2500.50',
  currency: 'DNR'
});
console.log(escrow.id);

Response

{
  "success": true,
  "data": {
    "id": "esc_5ftan1x",
    "buyerAddress": "0x3b6dbe334fe6faf71360dbbc74671a0c1c167608",
    "sellerAddress": "0xf251038d1dB96Ce1a733Ae92247E0A6F400F275E",
    "amount": "2500.50",
    "currency": "DNR",
    "status": "held"
  }
}

Apply for DNR Loan

Lock collateral and receive borrow amount in USD.

Request — TypeScript

const loan = await client.loans.apply({
  borrowerAddress: '0x3b6dbe334fe6faf71360dbbc74671a0c1c167608',
  collateralAmount: '5000',
  collateralCurrency: 'DNR',
  loanAmount: '2000',
  loanCurrency: 'USD'
});
console.log(loan.id, loan.totalRepayable);

Response

{
  "success": true,
  "data": {
    "id": "loan_5cjr3lt",
    "borrowerAddress": "0x3b6dbe334fe6faf71360dbbc74671a0c1c167608",
    "collateralAmount": "5000",
    "collateralCurrency": "DNR",
    "loanAmount": "2000",
    "loanCurrency": "USD",
    "status": "active",
    "totalRepayable": "2160.00"
  }
}