TYPES.md

BidKit Type Definitions

This document defines all TypeScript types used across BidKit modules. Use this as the authoritative reference when implementing.

Core Types

// ═══════════ CONFIGURATION ═══════════

export interface BidKitConfig {
  readonly okx: OKXConfig;
  readonly rpc: RPCConfig;
  readonly risk: RiskConfig;
  readonly x402: X402Config;
}

export interface OKXConfig {
  readonly apiKey: string;
  readonly secretKey: string;
  readonly passphrase: string;
  readonly baseUrl: string; // default: "https://www.okx.com"
}

export interface RPCConfig {
  readonly ethereum: string;
  readonly arbitrum: string;
}

export interface RiskConfig {
  readonly maxSingleExposurePct: number;    // default: 5
  readonly maxConcurrentAuctions: number;   // default: 3
  readonly securityThreshold: number;       // default: 70 (0-100)
  readonly clearingPriceCeiling: number;    // default: 2.0 (multiplier)
  readonly minAuctionDurationSec: number;   // default: 3600
  readonly maxSlippageBps: number;          // default: 300 (3%)
  readonly cooldownSec: number;             // default: 1800
}

export interface X402Config {
  readonly enabled: boolean;
  readonly receiverAddress: `0x${string}`;
  readonly pricingTier: 'free' | 'basic' | 'premium';
}

// ═══════════ DISCOVERY MODULE ═══════════

export interface AuctionRaw {
  readonly auctionAddress: `0x${string}`;
  readonly tokenAddress: `0x${string}`;
  readonly chainId: number;
  readonly totalSupply: bigint;
  readonly duration: number;           // seconds
  readonly floorPrice: bigint;
  readonly startBlock: number;
  readonly endBlock: number;
  readonly createdAt: number;          // unix timestamp
  readonly factoryAddress: `0x${string}`;
}

export interface TokenMetadata {
  readonly address: `0x${string}`;
  readonly name: string;
  readonly symbol: string;
  readonly decimals: number;
  readonly totalSupply: bigint;
  readonly holderCount: number;
  readonly topHoldersPct: number;      // top 10 holders % of supply
  readonly liquidityPools: readonly PoolInfo[];
  readonly marketCap: number | null;   // USD, null if no market
  readonly existingPrice: number | null;
}

export interface PoolInfo {
  readonly dex: string;
  readonly pairToken: string;
  readonly liquidity: number;          // USD
}

export interface SecurityReport {
  readonly tokenAddress: `0x${string}`;
  readonly overallScore: number;       // 0-100
  readonly isHoneypot: boolean;
  readonly ownershipRenounced: boolean;
  readonly buyTaxPct: number;
  readonly sellTaxPct: number;
  readonly hasProxy: boolean;
  readonly hasMintFunction: boolean;
  readonly riskLevel: 'low' | 'medium' | 'high' | 'critical';
}

export interface AuctionOpportunity {
  readonly auction: AuctionRaw;
  readonly token: TokenMetadata;
  readonly security: SecurityReport;
  readonly opportunityScore: number;   // 0-100
  readonly blocksRemaining: number;
  readonly timeRemainingMs: number;
  readonly passesSecurityFilter: boolean;
}

// ═══════════ VALUATION MODULE ═══════════

export interface ComparableToken {
  readonly address: `0x${string}`;
  readonly symbol: string;
  readonly marketCap: number;
  readonly volume24h: number;
  readonly priceChange24h: number;
  readonly holderCount: number;
  readonly similarityScore: number;    // 0-1
}

export interface SmartMoneySignal {
  readonly walletAddress: `0x${string}`;
  readonly action: 'buy' | 'sell' | 'hold';
  readonly amount: number;             // USD
  readonly timestamp: number;
  readonly isKOL: boolean;
  readonly winRate: number;            // 0-1
}

export interface CCAState {
  readonly auctionAddress: `0x${string}`;
  readonly currentClearingPrice: bigint;
  readonly totalBudgetCommitted: bigint;
  readonly activeBidderCount: number;
  readonly tokensDistributed: bigint;
  readonly tokensRemaining: bigint;
  readonly blocksRemaining: number;
  readonly priceTrajectory: 'rising' | 'stable' | 'falling';
  readonly blockPrices: readonly BlockPrice[];
}

export interface BlockPrice {
  readonly blockNumber: number;
  readonly clearingPrice: bigint;
  readonly tokensReleased: bigint;
}

export type BidStrategy = 'conservative' | 'moderate' | 'aggressive';

export interface BidRecommendation {
  readonly strategy: BidStrategy;
  readonly maxPrice: bigint;
  readonly budgetPct: number;          // % of available balance
  readonly estimatedFillProbability: number; // 0-1
  readonly expectedAvgPrice: bigint;
}

export interface ValuationReport {
  readonly auctionAddress: `0x${string}`;
  readonly timestamp: number;
  readonly fairValueRange: {
    readonly floor: bigint;
    readonly ceiling: bigint;
  };
  readonly confidence: number;         // 0-1
  readonly comparableTokens: readonly ComparableToken[];
  readonly smartMoneySignals: readonly SmartMoneySignal[];
  readonly ccaState: CCAState;
  readonly bidRecommendations: readonly BidRecommendation[];
}

// ═══════════ BIDDING MODULE ═══════════

export interface BidParams {
  readonly auctionAddress: `0x${string}`;
  readonly budget: bigint;             // USDC amount in wei
  readonly maxPrice: bigint;
  readonly prevTickPrice: bigint;
  readonly strategy: BidStrategy;
}

export interface SimulationResult {
  readonly success: boolean;
  readonly estimatedGas: bigint;
  readonly revertReason: string | null;
  readonly expectedOutcome: {
    readonly tokensExpected: bigint;
    readonly avgPriceExpected: bigint;
  } | null;
}

export interface BidReceipt {
  readonly txHash: `0x${string}`;
  readonly bidId: bigint;
  readonly auctionAddress: `0x${string}`;
  readonly budget: bigint;
  readonly maxPrice: bigint;
  readonly blockSubmitted: number;
  readonly status: 'pending' | 'confirmed' | 'failed';
  readonly timestamp: number;
}

// ═══════════ POST-AUCTION MODULE ═══════════

export type ExitStrategy = 'hold' | 'sell' | 'lp';

export interface PositionInfo {
  readonly auctionAddress: `0x${string}`;
  readonly tokenAddress: `0x${string}`;
  readonly tokensReceived: bigint;
  readonly avgEntryPrice: bigint;
  readonly currentPrice: bigint;
  readonly pnlBps: number;             // basis points
  readonly claimable: boolean;
  readonly claimed: boolean;
}

export interface StrategyDecision {
  readonly position: PositionInfo;
  readonly recommendedStrategy: ExitStrategy;
  readonly reasoning: string;
  readonly exitParams: SellParams | LPParams | null;
}

export interface SellParams {
  readonly tokenAddress: `0x${string}`;
  readonly amount: bigint;
  readonly minReceive: bigint;
  readonly route: 'okx-dex' | 'uniswap';
}

export interface LPParams {
  readonly tokenAddress: `0x${string}`;
  readonly amount: bigint;
  readonly pairToken: `0x${string}`;
  readonly tickLower: number;
  readonly tickUpper: number;
  readonly feeTier: number;
}

export interface ExitReceipt {
  readonly strategy: ExitStrategy;
  readonly txHash: `0x${string}` | null;
  readonly amountReceived: bigint | null;
  readonly pnlBps: number;
  readonly timestamp: number;
}

// ═══════════ RISK MODULE ═══════════

export interface PortfolioState {
  readonly totalBalance: bigint;       // USDC
  readonly activePositions: readonly PositionInfo[];
  readonly activeBids: readonly BidReceipt[];
  readonly totalExposurePct: number;
  readonly concurrentAuctions: number;
}

export interface RiskCheck {
  readonly passed: boolean;
  readonly violations: readonly string[];
  readonly availableBudget: bigint;    // max USDC allocatable
}

// ═══════════ x402 PAYMENTS ═══════════

export interface X402ServiceRequest {
  readonly service: 'discovery' | 'valuation' | 'bidding' | 'management';
  readonly params: Record<string, unknown>;
  readonly payerAddress: `0x${string}`;
  readonly paymentTxHash: `0x${string}`;
}

export interface X402ServiceResponse {
  readonly service: string;
  readonly result: unknown;
  readonly pricePaid: bigint;
  readonly timestamp: number;
}

// ═══════════ COMMON ═══════════

export interface BidKitError {
  readonly code: string;
  readonly message: string;
  readonly module: string;
  readonly details?: Record<string, unknown>;
}