账单与质押 API

账单与质押 API 提供了 9 个方法——4 个用于使用加密货币支付公用事业和服务账单，5 个用于质押加密货币赚取收益。

账单支付方法

方法	参数	返回值	描述
getBillProviders(country?, category?)	country?: string, category?: string	ApiResponse<BillProvider[]>	列出账单服务商，可选按国家和类别筛选。
validateBillAccount(providerId, accountNumber)	providerId: string, accountNumber: string	ApiResponse<BillAccountValidation>	验证客户在服务商处的账户号码。
payBill(request)	request: BillPaymentRequest	ApiResponse<BillPayment>	提交账单支付。
getBillHistory(options?)	options?: BillHistoryOptions	ApiResponse<BillPayment[]>	返回用户的账单支付历史。

质押方法

方法	参数	返回值	描述
getStakingPools(chainId?)	chainId?: string	ApiResponse<StakingPool[]>	列出可用的质押池，可选按链筛选。
getStakingPositions()	--	ApiResponse<StakingPosition[]>	返回用户当前活跃的质押持仓。
stake(request)	request: StakeRequest	ApiResponse<StakingPosition>	将代币质押到质押池中。
unstake(positionId, amount?)	positionId: string, amount?: string	ApiResponse<UnstakeResult>	从持仓中解除质押（全部或部分）。
claimStakingRewards(positionId)	positionId: string	ApiResponse<ClaimResult>	领取累积的质押奖励。

类型

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';
}

示例

支付账单

// 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 });

质押代币

// 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}`);
}

后续步骤

• On-ramp & Off-ramp API -- 使用法币买卖加密货币。
• Bridge & Gas API -- 跨链桥接代币和估算 Gas。