opensea-js/lib/types.d.ts

TypeScript SDK for the OpenSea marketplace helps developers build new experiences using NFTs and our marketplace data

import { BigNumberish } from "ethers";
import type { OrderV2 } from "./orders/types";
/**
 * Events emitted by the SDK which can be used by frontend applications
 * to update state or show useful messages to users.
 * @category Events
 */
export declare enum EventType {
    /**
     * Emitted when the transaction is sent to the network and the application
     * is waiting for the transaction to be mined.
     */
    TransactionCreated = "TransactionCreated",
    /**
     * Emitted when the transaction has succeeded is mined and confirmed.
     */
    TransactionConfirmed = "TransactionConfirmed",
    /**
     * Emitted when the transaction has failed to be submitted.
     */
    TransactionDenied = "TransactionDenied",
    /**
     * Emitted when the transaction has failed to be mined.
     */
    TransactionFailed = "TransactionFailed",
    /**
     * Emitted when the {@link OpenSeaSDK.wrapEth} method is called.
     */
    WrapEth = "WrapEth",
    /**
     * Emitted when the {@link OpenSeaSDK.unwrapWeth} method is called.
     */
    UnwrapWeth = "UnwrapWeth",
    /**
     * Emitted when fulfilling a public or private order.
     */
    MatchOrders = "MatchOrders",
    /**
     * Emitted when the {@link OpenSeaSDK.cancelOrder} method is called.
     */
    CancelOrder = "CancelOrder",
    /**
     * Emitted when the {@link OpenSeaSDK.approveOrder} method is called.
     */
    ApproveOrder = "ApproveOrder",
    /**
     * Emitted when the {@link OpenSeaSDK.transfer} method is called.
     */
    Transfer = "Transfer"
}
/**
 * Data that gets sent with each {@link EventType}
 * @category Events
 */
export interface EventData {
    /**
     * Wallet address of the user who initiated the event.
     */
    accountAddress?: string;
    /**
     * Amount of ETH sent when wrapping or unwrapping.
     */
    amount?: BigNumberish;
    /**
     * The transaction hash of the event.
     */
    transactionHash?: string;
    /**
     * The {@link EventType} of the event.
     */
    event?: EventType;
    /**
     * Error which occurred when transaction was denied or failed.
     */
    error?: unknown;
    /**
     * The {@link OrderV2} object.
     */
    orderV2?: OrderV2;
}
/**
 * OpenSea API configuration object
 * @param chain `Chain` to use. Defaults to Ethereum Mainnet (`Chain.Mainnet`)
 * @param apiKey API key to use
 * @param apiBaseUrl Optional base URL to use for the API
 */
export interface OpenSeaAPIConfig {
    chain?: Chain;
    apiKey?: string;
    apiBaseUrl?: string;
}
/**
 * Each of the possible chains that OpenSea supports.
 * ⚠️NOTE: When adding to this list, also add to the following functions:
 * - `getChainId`
 * - `getListingPaymentToken`
 * - `getOfferPaymentToken`
 * - `getNativeWrapTokenAddress` (if getOfferPaymentToken isn't the wrapped native asset)
 */
export declare enum Chain {
    Mainnet = "ethereum",
    Polygon = "matic",
    Base = "base",
    Blast = "blast",
    Arbitrum = "arbitrum",
    ArbitrumNova = "arbitrum_nova",
    Avalanche = "avalanche",
    Optimism = "optimism",
    Solana = "solana",
    Zora = "zora",
    Sei = "sei",
    B3 = "b3",
    BeraChain = "bera_chain",
    ApeChain = "ape_chain",
    Flow = "flow",
    Ronin = "ronin",
    Abstract = "abstract",
    Shape = "shape",
    Unichain = "unichain",
    Gunzilla = "gunzilla"
}
/**
 * Order side: listing (ask) or offer (bid)
 */
export declare enum OrderSide {
    LISTING = "ask",
    OFFER = "bid"
}
/**
 * Token standards
 */
export declare enum TokenStandard {
    ERC20 = "ERC20",
    ERC721 = "ERC721",
    ERC1155 = "ERC1155"
}
/**
 * The collection's approval status within OpenSea.
 * Can be one of:
 * - not_requested: brand new collections
 * - requested: collections that requested safelisting on our site
 * - approved: collections that are approved on our site and can be found in search results
 * - verified: verified collections
 */
export declare enum SafelistStatus {
    NOT_REQUESTED = "not_requested",
    REQUESTED = "requested",
    APPROVED = "approved",
    VERIFIED = "verified",
    DISABLED_TOP_TRENDING = "disabled_top_trending"
}
/**
 * Collection fees
 * @category API Models
 */
export interface Fee {
    fee: number;
    recipient: string;
    required: boolean;
}
/**
 * Generic Blockchain Asset.
 * @category API Models
 */
export interface Asset {
    /** The asset's token ID, or null if ERC-20 */
    tokenId: string | null;
    /** The asset's contract address */
    tokenAddress: string;
    /** The token standard (e.g. "ERC721") for this asset */
    tokenStandard?: TokenStandard;
    /** Optional for ENS names */
    name?: string;
    /** Optional for fungible items */
    decimals?: number;
}
/**
 * Generic Blockchain Asset, with tokenId required.
 * @category API Models
 */
export interface AssetWithTokenId extends Asset {
    /** The asset's token ID */
    tokenId: string;
}
/**
 * Generic Blockchain Asset, with tokenStandard required.
 * @category API Models
 */
export interface AssetWithTokenStandard extends Asset {
    /** The token standard (e.g. "ERC721") for this asset */
    tokenStandard: TokenStandard;
}
interface OpenSeaCollectionStatsIntervalData {
    interval: "one_day" | "seven_day" | "thirty_day";
    volume: number;
    volume_diff: number;
    volume_change: number;
    sales: number;
    sales_diff: number;
    average_price: number;
}
/**
 * OpenSea Collection Stats
 * @category API Models
 */
export interface OpenSeaCollectionStats {
    total: {
        volume: number;
        sales: number;
        average_price: number;
        num_owners: number;
        market_cap: number;
        floor_price: number;
        floor_price_symbol: string;
    };
    intervals: OpenSeaCollectionStatsIntervalData[];
}
export interface RarityStrategy {
    strategyId: string;
    strategyVersion: string;
    calculatedAt: string;
    maxRank: number;
    tokensScored: number;
}
/**
 * OpenSea collection metadata.
 * @category API Models
 */
export interface OpenSeaCollection {
    /** Name of the collection */
    name: string;
    /** The identifier (slug) of the collection */
    collection: string;
    /** Description of the collection */
    description: string;
    /** Image for the collection */
    imageUrl: string;
    /** Banner image for the collection */
    bannerImageUrl: string;
    /** Owner address of the collection */
    owner: string;
    /** The collection's safelist status */
    safelistStatus: SafelistStatus;
    /** The category of the collection */
    category: string;
    /** If the collection is disabled */
    isDisabled: boolean;
    /** If the collection is NSFW (not safe for work) */
    isNSFW: boolean;
    /** If trait offers are enabled */
    traitOffersEnabled: boolean;
    /** If collection offers are enabled */
    collectionOffersEnabled: boolean;
    /** The OpenSea url for the collection */
    openseaUrl: string;
    /** The project url for the collection */
    projectUrl: string;
    /** The wiki url for the collection */
    wikiUrl: string;
    /** The discord url for the collection */
    discordUrl: string;
    /** The telegram url for the collection */
    telegramUrl: string;
    /** The twitter username for the collection */
    twitterUsername: string;
    /** The instagram username for the collection */
    instagramUsername: string;
    /** The contracts for the collection */
    contracts: {
        address: string;
        chain: Chain;
    }[];
    /** Accounts allowed to edit this collection */
    editors: string[];
    /** The fees for the collection */
    fees: Fee[];
    /** The rarity strategy for the collection */
    rarity: RarityStrategy | null;
    /** Payment tokens allowed for orders for this collection */
    paymentTokens: OpenSeaPaymentToken[];
    /** The total supply of the collection (minted minus burned) */
    totalSupply: number;
    /** The created date of the collection */
    createdDate: string;
    /** When defined, the zone required for orders for the collection */
    requiredZone?: string;
}
/**
 * Full annotated Fungible Token spec with OpenSea metadata
 */
export interface OpenSeaPaymentToken {
    name: string;
    symbol: string;
    decimals: number;
    address: string;
    chain: Chain;
    imageUrl?: string;
    ethPrice?: string;
    usdPrice?: string;
}
/**
 * Query interface for payment tokens
 * @category API Models
 */
export interface OpenSeaPaymentTokensQuery {
    symbol?: string;
    address?: string;
    limit?: number;
    next?: string;
}
/**
 * OpenSea Account
 * @category API Models
 */
export interface OpenSeaAccount {
    address: string;
    username: string;
    profileImageUrl: string;
    bannerImageUrl: string;
    website: string;
    socialMediaAccounts: SocialMediaAccount[];
    bio: string;
    joinedDate: string;
}
/**
 * Social media account
 * @category API Models
 */
export interface SocialMediaAccount {
    platform: string;
    username: string;
}
/**
 * Enhanced Error type for rate limit errors that includes retry-after information
 * @category API Models
 */
export interface OpenSeaRateLimitError extends Error {
    /** The number of seconds to wait before retrying the request */
    retryAfter?: number;
    /** The response body from the API */
    responseBody?: unknown;
}
export {};