Frontend API Reference

React hooks and utilities for integrating with AgoráX.

Contract Interaction Hooks

useContractWhitelist

Main hook for contract write operations.

import { useContractWhitelist } from '@/hooks/contracts/useContractWhitelist';

const {
  placeOrder,
  fillOrder,
  cancelOrder,
  collectProceeds
} = useContractWhitelist();

useContractWhitelistRead

Hook for reading whitelist data from the contract.

import { useContractWhitelistRead } from '@/hooks/contracts/useContractWhitelistRead';

const { activeTokens, isLoading } = useContractWhitelistRead();

useOpenPositions

Hook for fetching user's orders and marketplace data.

import { useOpenPositions } from '@/hooks/contracts/useOpenPositions';

// User's own orders
const { openOrders, expiredOrders, isLoading } = useOpenPositions(address);

// All marketplace orders
const { allOrders } = useOpenPositions(undefined, true);

Data Hooks

useTokenPrices

Fetch current token prices from DEX pairs.

Price value meanings:

• price > 0 - Valid market price
• price === 0 - Failed to fetch
• price === -1 - No price source

useLimitOrderPricing

Centralized pricing logic for the limit order form.

import { useLimitOrderPricing } from '@/hooks/useLimitOrderPricing';

const pricing = useLimitOrderPricing({
  sellToken,
  buyToken,
  getPrice,
});

// Returns handlers and calculated values
pricing.handlePercentageClick(5); // +5%
pricing.handleLimitPriceChange(1.5);
pricing.handleSellAmountChange("1000");

useClaimableOrdersCount

Count orders with unclaimed proceeds (used for NavBar badge).

import { useClaimableOrdersCount } from '@/hooks/useClaimableOrdersCount';

const { claimableCount, isLoading } = useClaimableOrdersCount();

Utilities

getContractAddress

Get the correct contract address for a given chain ID.

import { getContractAddress } from '@/config/testing';

const address = getContractAddress(chainId);
// 369 -> mainnet address
// 943 -> testnet address

getBlockExplorerTxUrl

Generate block explorer URLs for transactions.

import { getBlockExplorerTxUrl } from '@/utils/blockExplorer';

const url = getBlockExplorerTxUrl(chainId, txHash);
// 369 -> otter.pulsechain.com
// 943 -> scan.v4.testnet.pulsechain.com

Rate Limits & Security

API Rate Limiting

All API routes are rate limited to 300 requests/minute per IP address per endpoint.

Transaction Timeouts

• Approvals: 60 seconds
• Transactions: 60 seconds
• Approval verification: 30 seconds

Amount Validation

• Overflow protection (max 1e30)
• Decimal precision validation
• Dust attack prevention (min 1e-18)

Token Constants

import { TOKEN_CONSTANTS } from '@/constants/crypto';

// Each token has:
interface TokenConstant {
  t: string;      // Full name
  ticker: string; // Symbol
  a?: string;     // Contract address (undefined for PLS)
  d: number;      // Decimals
  dexs?: string[];// DEX pair addresses for pricing
}

// Whitelist filtering
const { activeTokens } = useContractWhitelistRead();
const whitelistedSet = new Set(
  activeTokens.map(t => t.tokenAddress.toLowerCase())
);

const tradableTokens = TOKEN_CONSTANTS.filter(t =>
  whitelistedSet.has(t.a?.toLowerCase() ?? '')
);

Smart Contract

Data Structures