@kwespay/client

TypeScript SDK for KwesPay — accept crypto payments in your app with minimal setup.

All pricing, signing, and contract addresses are managed server-side. You initialise the client, request a quote, and execute the payment. Nothing else is required.

---

Prerequisites

Before installing the SDK, you need a KwesPay vendor account and an API key.

1. Go to app.kwespay.xyz and create an account
2. Create a vendor profile — this gives you your Vendor ID
3. Navigate to API Keys and generate a key — this is your API Key

Keep both values handy; you will need them to initialise the client.

---

Installation

npm install @kwespay/client

yarn add @kwespay/client

pnpm add @kwespay/client

---

Requirements

• Node.js 18+
• TypeScript 5+
• An EIP-1193 compatible wallet provider (MetaMask, WalletConnect, etc.)
• A KwesPay API key (see Prerequisites)

---

Quick Start

import { KwesPayClient } from "@kwespay/client";

const client = new KwesPayClient({ apiKey: "your-api-key" });

const payload = await client.quote({
  vendorIdentifier: "your-vendor-id",
  fiatAmount: 10,
  fiatCurrency: "USD",
  cryptoCurrency: "USDC",
  network: "base",
  payerWalletAddress: "0xabc...",
});

const result = await client.pay({
  provider: window.ethereum,
  payload,
  onStatus: (title, detail) => console.log(title, detail),
});

console.log(result.txHash);

---

API Reference

new KwesPayClient(config)

Creates a new client instance.

Parameter	Type	Required	Description
config.apiKey	string	Yes	Your KwesPay API key

---

client.validateKey()

Validates the configured API key and returns its scope.

const result = await client.validateKey();

if (result.isValid) {
  console.log(result.vendorInfo);
  console.log(result.scope.allowedNetworks);
} else {
  console.error(result.error);
}

Returns — { isValid: true, keyId, keyLabel, activeFlag, expirationDate, vendorInfo, scope } or { isValid: false, error }.

---

client.quote(params)

Fetches a price quote and prepares a transaction payload in a single call. The returned payload is passed directly to client.pay().

const payload = await client.quote({
  vendorIdentifier: "your-vendor-id",
  fiatAmount: 25.00,
  fiatCurrency: "USD",        // optional, defaults to "USD"
  cryptoCurrency: "USDC",
  network: "base",
  payerWalletAddress: "0xabc...",
});

Parameter	Type	Required	Description
vendorIdentifier	string	Yes	Your vendor UUID from app.kwespay.xyz
fiatAmount	number	Yes	Amount in fiat to charge
fiatCurrency	string	No	Fiat currency code. Defaults to "USD"
cryptoCurrency	TokenSymbol	Yes	Token to accept
network	NetworkKey	Yes	Target blockchain network
payerWalletAddress	string	Yes	The payer's wallet address

Returns — TransactionPayload

---

client.pay(params)

Executes the on-chain payment. Handles network switching, token approval, and transaction submission automatically.

const result = await client.pay({
  provider: window.ethereum,
  payload,
  onStatus: (title, detail) => {
    console.log(`[${title}] ${detail}`);
  },
});

Parameter	Type	Required	Description
provider	EIP1193Provider	Yes	Wallet provider
payload	TransactionPayload	Yes	Payload from client.quote()
onStatus	(title, detail) => void	No	Progress callback

The onStatus callback fires at each stage of the payment flow:

Title	Fired when
Checking balance	Verifying wallet has sufficient funds
Switching network	Requesting network change in wallet
Checking approval	Reading current ERC-20 allowance
Approve token	Requesting ERC-20 approval from user
Waiting for approval	Approval tx is confirming on-chain
Confirm payment	Requesting payment tx from user
Waiting for confirmation	Payment tx is confirming on-chain

Returns — PaymentResult

interface PaymentResult {
  txHash: string;
  blockNumber: number;
  transactionReference: string;
  paymentIdBytes32: string;
}

---

client.getTransactionStatus(transactionReference)

Polls the KwesPay backend for the current status of a transaction.

const status = await client.getTransactionStatus("txn_ref_here");
console.log(status.transactionStatus); // "completed"

Returns — TransactionStatusResult

interface TransactionStatusResult {
  transactionReference: string;
  transactionStatus: TransactionStatus;
  blockchainHash: string | null;
  blockchainNetwork: string | null;
  displayAmount: number;
  cryptoCurrency: string;
  payerWalletAddress: string;
  initiatedAt: string;
}

---

Supported Networks

Key	Network
ethereum	Ethereum Mainnet
sepolia	Ethereum Sepolia (testnet)
base	Base Mainnet
baseSepolia	Base Sepolia (testnet)
polygon	Polygon Mainnet
polygonAmoy	Polygon Amoy (testnet)
lisk	Lisk Mainnet
liskTestnet	Lisk Testnet
MezoTestnet	Mezo Testnet

---

Supported Tokens

ETH, MATIC, USDT, USDC, USDC.E, USDBC, DAI, LSK, MUSD

Custom token addresses are also accepted as a plain string.

---

Error Handling

All errors are thrown as KwesPayError instances with a code property.

import { KwesPayClient, KwesPayError } from "@kwespay/client";

try {
  const payload = await client.quote({ ... });
  const result = await client.pay({ provider, payload });
} catch (err) {
  if (err instanceof KwesPayError) {
    switch (err.code) {
      case "WALLET_REJECTED":
        console.error("User cancelled the transaction.");
        break;
      case "INSUFFICIENT_BALANCE":
        console.error("Not enough funds:", err.message);
        break;
      case "WRONG_NETWORK":
        console.error("Network mismatch:", err.message);
        break;
      case "QUOTE_EXPIRED":
        console.error("Quote expired. Request a new one.");
        break;
      default:
        console.error(`Payment failed [${err.code}]:`, err.message);
    }
  }
}

Error Codes

Code	Description
INVALID_KEY	API key is missing, invalid, or inactive
QUOTE_EXPIRED	Quote TTL has elapsed
QUOTE_USED	Quote has already been used for a transaction
QUOTE_NOT_FOUND	Quote ID does not exist
TRANSACTION_FAILED	Payload is missing required fields
WALLET_REJECTED	User rejected the transaction in their wallet
APPROVAL_REJECTED	User rejected the ERC-20 approval in their wallet
INSUFFICIENT_BALANCE	Wallet lacks funds or gas
CONTRACT_ERROR	On-chain call reverted or receipt timed out
WRONG_NETWORK	Wallet is on the wrong chain and could not switch
NETWORK_ERROR	HTTP or connectivity failure reaching the API
UNKNOWN	Unclassified server-side error

---

TypeScript

The SDK is written in TypeScript and ships its own types. No additional @types packages are required.

Key types exported from the package:

import type {
  KwesPayConfig,
  QuoteParams,
  TransactionPayload,
  TransactionStatus,
  TransactionStatusResult,
  PayParams,
  PaymentResult,
  NetworkKey,
  TokenSymbol,
  EIP1193Provider,
  KwesPayErrorCode,
} from "@kwespay/client";

---

License

MIT