Types Reference

interface Trade {
  id: string;                    // Unique trade ID (UUID)
  type: TradeType;               // "deposit" or "withdraw"
  source: TradeSource;           // "client" or "self" (origin flow)
  status: TradeStatus;           // Current trade status
  game: string;                  // Game app ID ("730" or "252490")

  // Participants
  merchantId: string;            // Your merchant ID
  clientUserId: string;          // Internal client user ID
  clientSteamID: string;         // User's Steam ID 64
  clientTradeUrl: string;        // User's Steam trade URL

  // Items and pricing
  items: Item[];                 // Items in this trade
  totalPrice: number;            // Total value in USD

  // Instant deposit fields (deposits only)
  preCredit?: number;            // Amount credited instantly (USD)
  pendingCredit?: number;        // Amount held until "completed" (USD)
  isInstant?: boolean;           // Whether instant credit was requested
  collateral?: {
    merchant: number;            // Merchant collateral portion
    provider: number;            // Provider collateral portion
  };

  // Tracking
  externalId?: string;           // Your tracking ID (from externalId param)
  externalClientUserId?: string; // Your user ID (from clientId param)
  offerID?: string;              // Steam trade offer ID (present from "active" onward)

  // Timing
  holdEndDate?: Date;            // When the Steam hold expires (present from "hold" onward)
  activeAt?: Date;               // When the trade offer went live at the user (present from "active" onward)
  autoCancelAt?: Date;           // When items the seller hasn't sent will be canceled automatically.
                                 //   Items already offered to the user or in Steam hold are never
                                 //   auto-canceled. Absent when auto-cancel is off, and on Rust.
  createdAt: Date;
  updatedAt: Date;

  // Status-specific
  revertedBy?: RevertedBy;       // Who reversed the trade (status === "reverted")
  error?: string;                // Failure reason. Withdrawals: a TradeFailureCode, set only when the
                                 //   whole trade failed with one shared cause. Deposits: a Steam error key.

  // Bot details
  botInfo?: {
    name: string;
    avatar?: string;
    steamId?: string;
    joined?: Date;
  };
}

interface Item {
  // Identity
  id: string;                    // On CS2 withdraw items, the listing id you quoted — stable for the
                                 //   item's whole life. On inventory and deposit items, the encoded
                                 //   item id. Cancel endpoints accept it alongside externalId.
  externalId?: string;           // Your own per-item reference, when you supplied one at buy time.
                                 //   Cancel accepts it in place of id. Omitted on stacked Rust rows,
                                 //   which stand for several items at once.
  assetId?: string;              // Raw Steam assetid. Always present on inventory listings and deposit
                                 //   items; omitted on withdraw items until the item lands in the
                                 //   recipient's Steam inventory.
  appid: number;                 // Game app ID (730 or 252490)

  // Description — omitted on bare withdraw items where AssetPay has no Steam-side
  // metadata yet (you supplied only itemId + price). Always present for inventory,
  // market, and post-completion trade items.
  name?: string;                 // Display name (e.g. "AK-47 | Redline")
  marketHashName?: string;       // Full market name (e.g. "AK-47 | Redline (Field-Tested)")
  type?: string;                 // Item type (e.g. "Rifle", "Knife")
  iconUrl?: string;              // Steam image hash (use with Steam CDN base URL)

  // Trade state
  tradable: boolean;             // Whether the item can be traded
  amount?: number;               // Stack count for Rust items

  // Pricing
  marketPrice?: number;          // Market reference price (USD)
  offer?: ItemOffer;             // See ItemOffer below

  // Cosmetic attributes
  exterior?: string;             // "Factory New", "Minimal Wear", etc.
  rarity?: string;               // "Consumer Grade", "Covert", etc.
  color?: string;                // Rarity color hex (e.g. "#EB4B4B")
  wear?: string;                 // Float value as string
  paintSeed?: number;            // Paint seed number
  previewToken?: string;         // Steam inspect/preview token (CS2). Present on inventory and
                                 //   autoseller-pool (self-owned) items; absent on third-party
                                 //   marketplace listings.
  doppler?: Doppler;             // Doppler phase details
  fade?: Fade;                   // Fade percentage details
  hardened?: Hardened;           // Case Hardened pattern details

  // Applied items
  stickers?: Sticker[];          // Applied stickers
  charm?: Charm;                 // Applied charm (CS2 only)

  // Market-specific
  botInfo?: {                    // Holding bot identity — present on autoseller-pool market items
    name: string;
    avatar?: string;
    steamId?: string;
    joined?: Date;
  };

  // Withdrawal-specific (only set on items belonging to a withdraw trade)
  status?: TradeStatus;          // Per-item purchase status, mirrors Trade.status
  error?: TradeFailureCode;      // Failure code — present only on failed withdraw items
}

interface ItemOffer {
  price: number;                 // Offer price in USD
  reference?: string;            // Parent product reference (e.g. "0010f8d48278ccb8")
                                 //   — the id you query /market/item with. The
                                 //   listing-specific id is the surrounding Item.id.
                                 //   Present on market/inventory items. Omitted on
                                 //   freshly-initiated withdraw items; backfilled
                                 //   from callbacks as the trade progresses.
  delivery?: DeliveryMode;       // "standard" or "instant" (market items only)
  maxAmount?: number;            // Max quantity for stackable items (inventory only)
  accepted?: boolean;            // Whether the item is accepted for deposit (deposit-side inventory only)
}

interface Sticker {
  name: string;                  // Sticker display name
  marketHashName?: string;       // Sticker's own market hash name, for deep-linking
  slot: number;                  // Position on the weapon (0-4)
  wear?: number;                 // Sticker wear (0 = perfect, 1 = scraped off)
  iconUrl: string;               // Sticker image URL
}

interface Charm {
  name: string;                  // Charm display name
  marketHashName?: string;       // Charm's own market hash name, for deep-linking
  iconUrl: string;               // Charm image URL
}

interface Doppler {
  status?: number;               // Marketplace-issued status code (market listings only)
  name: string;                  // Phase name (e.g. "Phase 1", "Ruby", "Sapphire")
  paintIndex?: number;           // Steam paint index, if known
}

interface Fade {
  percentage: number;            // Fade percentage (0-100)
}

interface Hardened {
  status: number;                // Case Hardened tier code
  name: string;                  // Pattern name (e.g. "Blue Gem")
}

type TradeStatus =
  | 'initiated'   // Trade created. Withdrawals: approval gate (merchant wallet not yet debited)
  | 'pending'     // (Withdrawals only) Supplier is sourcing the item / creating the purchase
  | 'active'      // Steam trade offer sent to the user, awaiting acceptance
  | 'hold'        // User accepted; Steam hold window running (carries offerID + holdEndDate)
  | 'completed'   // Trade finished successfully
  | 'failed'      // Trade failed at some point
  | 'canceled'    // Trade was canceled before completion (no penalty)
  | 'declined'    // End user declined / let the Steam offer expire. Withdrawals: refund minus a 2% penalty
  | 'reverted';   // Previously completed trade was reversed (see revertedBy)

type TradeType =
  | 'deposit'    // User selling items to merchant
  | 'withdraw';  // User buying items from market

type TradeSource =
  | 'client'    // Initiated by an end-user via /client/trading/*
  | 'self';     // Merchant self-trade via /secure/sell or /secure/buy

type DeliveryMode =
  | 'standard'  // Trade-offer delivery (bot sources from a supplier and sends a Steam trade offer)
  | 'instant';  // Instant delivery (item already pre-positioned with the bot)

type RevertedBy =
  | 'supplier'   // Marketplace supplier reversed (withdrawals only)
  | 'user';      // End user reversed

type TradeFailureCode =
  | 'LISTING_UNAVAILABLE'      // Listing sold / delisted / out of stock — retry another listing
  | 'PRICE_CHANGED'            // Price moved above your ceiling — re-quote
  | 'TRADE_URL_INVALID'        // Recipient's Steam trade URL is invalid or escrow-blocked
  | 'STEAM_ACCOUNT_RESTRICTED' // Recipient's Steam account can't receive (VAC / ban / hold / private)
  | 'MARKET_UNAVAILABLE'       // Temporary upstream or our-side issue — retry later
  | 'PURCHASE_FAILED';         // Unclassified failure (catch-all)

enum GameId {
  CS2  = 730,
  RUST = 252490,
}

interface CallbackBody {
  trade: Trade;
}