Skip to main content

Bills & Staking API

The Bills and Staking API provides 9 methods -- 4 for paying utility and service bills with crypto, and 5 for staking crypto to earn yield.

Bill Payment Methods​

MethodParametersReturnsDescription
getBillProviders(country?, category?)country?: string, category?: stringApiResponse<BillProvider[]>Lists bill providers, optionally filtered by country and category.
validateBillAccount(providerId, accountNumber)providerId: string, accountNumber: stringApiResponse<BillAccountValidation>Validates a customer account number with the provider.
payBill(request)request: BillPaymentRequestApiResponse<BillPayment>Submits a bill payment.
getBillHistory(options?)options?: BillHistoryOptionsApiResponse<BillPayment[]>Returns the user's bill payment history.

Staking Methods​

MethodParametersReturnsDescription
getStakingPools(chainId?)chainId?: stringApiResponse<StakingPool[]>Lists available staking pools, optionally filtered by chain.
getStakingPositions()--ApiResponse<StakingPosition[]>Returns the user's active staking positions.
stake(request)request: StakeRequestApiResponse<StakingPosition>Stakes tokens in a staking pool.
unstake(positionId, amount?)positionId: string, amount?: stringApiResponse<UnstakeResult>Unstakes tokens from a position (full or partial).
claimStakingRewards(positionId)positionId: stringApiResponse<ClaimResult>Claims accrued staking rewards.

Types​

BillProvider​

interface BillProvider {
  id: string;
  name: string;
  /** Category (e.g. "electricity", "internet", "water", "tv"). */
  category: string;
  country: string;
  /** Accepted crypto currencies for payment. */
  acceptedCurrencies: string[];
  logoUrl?: string;
  /** Whether account validation is supported. */
  supportsValidation: boolean;
}

BillAccountValidation​

interface BillAccountValidation {
  valid: boolean;
  /** Customer name on file (returned when valid). */
  customerName?: string;
  /** Outstanding balance, if available. */
  outstandingBalance?: string;
  currency?: string;
}

BillPaymentRequest​

interface BillPaymentRequest {
  /** Provider ID. */
  providerId: string;
  /** Customer account number with the provider. */
  accountNumber: string;
  /** Payment amount in the provider's currency. */
  amount: string;
  /** Crypto currency to pay with (e.g. "USDC"). */
  payCurrency: string;
  /** Chain to pay from. */
  chainId: string;
  /** Wallet address funding the payment. */
  walletAddress: string;
}

BillPayment​

interface BillPayment {
  id: string;
  providerId: string;
  providerName: string;
  accountNumber: string;
  amount: string;
  currency: string;
  payCurrency: string;
  /** Crypto amount charged. */
  cryptoAmount: string;
  txHash?: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  createdAt: string;
  completedAt?: string;
}

BillHistoryOptions​

interface BillHistoryOptions {
  providerId?: string;
  status?: 'pending' | 'completed' | 'failed';
  limit?: number;
  cursor?: string;
}

StakingPool​

interface StakingPool {
  id: string;
  name: string;
  /** Token being staked. */
  stakingToken: string;
  stakingTokenAddress: string;
  /** Token received as reward. */
  rewardToken: string;
  rewardTokenAddress: string;
  chainId: string;
  /** Current annual percentage yield. */
  apy: number;
  /** Total value locked in the pool. */
  tvl: string;
  minStake: string;
  maxStake?: string;
  /** Lock-up period in days. 0 means flexible. */
  lockDays: number;
  status: 'active' | 'paused' | 'closed';
}

StakeRequest​

interface StakeRequest {
  /** Staking pool ID. */
  poolId: string;
  /** Amount of tokens to stake. */
  amount: string;
  /** Wallet address. */
  walletAddress: string;
}

StakingPosition​

interface StakingPosition {
  id: string;
  poolId: string;
  poolName: string;
  stakingToken: string;
  /** Amount currently staked. */
  stakedAmount: string;
  /** Current USD value of staked amount. */
  stakedValueUsd: string;
  /** Accrued rewards (claimable). */
  pendingRewards: string;
  pendingRewardsUsd: string;
  rewardToken: string;
  apy: number;
  /** Unlock date. Null if flexible staking. */
  unlockDate?: string;
  status: 'active' | 'unlocking' | 'withdrawn';
  createdAt: string;
}

UnstakeResult​

interface UnstakeResult {
  positionId: string;
  /** Amount unstaked. */
  unstakedAmount: string;
  /** Remaining staked amount (for partial unstake). */
  remainingStaked: string;
  txHash?: string;
  /** Time until tokens are available (for locked pools). */
  cooldownEndsAt?: string;
  status: 'processing' | 'cooldown' | 'completed';
}

ClaimResult​

interface ClaimResult {
  positionId: string;
  rewardToken: string;
  /** Amount of rewards claimed. */
  claimedAmount: string;
  claimedValueUsd: string;
  txHash?: string;
  status: 'processing' | 'completed' | 'failed';
}

Examples​

Pay a Bill​

// 1. Find providers
const providersRes = await engine.getBillProviders('NG', 'electricity');

if (providersRes.success && providersRes.data) {
  for (const p of providersRes.data) {
    console.log(`${p.name} (${p.id}) - ${p.category}`);
  }
}

// 2. Validate the account
const validRes = await engine.validateBillAccount('prov_ekedc', '04123456789');

if (validRes.success && validRes.data?.valid) {
  console.log('Customer:', validRes.data.customerName);
}

// 3. Pay the bill
const payRes = await engine.payBill({
  providerId: 'prov_ekedc',
  accountNumber: '04123456789',
  amount: '5000',
  payCurrency: 'USDC',
  chainId: 'ethereum',
  walletAddress: '0xABC...',
});

if (payRes.success && payRes.data) {
  console.log('Payment submitted:', payRes.data.id);
  console.log('Status:', payRes.data.status);
}

// 4. View payment history
const historyRes = await engine.getBillHistory({ limit: 10 });

Stake Tokens​

// 1. List staking pools
const poolsRes = await engine.getStakingPools('ethereum');

if (poolsRes.success && poolsRes.data) {
  for (const pool of poolsRes.data) {
    console.log(`${pool.name} | APY: ${pool.apy}% | TVL: $${pool.tvl} | Lock: ${pool.lockDays}d`);
  }
}

// 2. Stake tokens
const stakeRes = await engine.stake({
  poolId: 'pool_eth_staking',
  amount: '10',
  walletAddress: '0xABC...',
});

if (stakeRes.success && stakeRes.data) {
  console.log('Staked:', stakeRes.data.stakedAmount, stakeRes.data.stakingToken);
}

// 3. View positions
const positionsRes = await engine.getStakingPositions();

if (positionsRes.success && positionsRes.data) {
  for (const pos of positionsRes.data) {
    console.log(`${pos.poolName} | Staked: ${pos.stakedAmount} | Rewards: ${pos.pendingRewards}`);
  }
}

// 4. Claim rewards
const claimRes = await engine.claimStakingRewards('pos_abc123');

if (claimRes.success && claimRes.data) {
  console.log(`Claimed ${claimRes.data.claimedAmount} ${claimRes.data.rewardToken}`);
}

// 5. Unstake (partial)
const unstakeRes = await engine.unstake('pos_abc123', '5');

if (unstakeRes.success && unstakeRes.data) {
  console.log(`Unstaked: ${unstakeRes.data.unstakedAmount}`);
  console.log(`Remaining: ${unstakeRes.data.remainingStaked}`);
}

Next Steps​