openapi: 3.1.0
info:
  title: OpenSea Account Endpoints API
  description: The API for OpenSea
  contact:
    name: OpenSea
    url: https://www.opensea.io
    email: contact@opensea.io
  version: 2.0.0
servers:
- url: https://api.opensea.io
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Account Endpoints
  description: Account endpoints to retrieve OpenSea account profiles and resolve identifiers
paths:
  /api/v2/accounts/{address_or_username}:
    get:
      tags:
      - Account Endpoints
      summary: Get an OpenSea account profile
      description: Get an OpenSea Account Profile including details such as bio, social media usernames, and profile image.
      operationId: get_account
      parameters:
      - name: address_or_username
        in: path
        description: The blockchain address or username of the account to retrieve
        required: true
        schema:
          type: string
        example: 0x8ba1f109551bD432803012645Hac136c94C19D6e
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/accounts/resolve/{identifier}:
    get:
      tags:
      - Account Endpoints
      summary: Resolve an account identifier
      description: Resolve an ENS name (e.g. vitalik.eth), OpenSea username, or wallet address to canonical account info including address, username, and ENS name. The ENS path performs both forward resolution (name → address) and reverse lookup (address → canonical primary name). The address and ENS paths perform enrichment calls (username + ENS reverse lookup) in parallel. The username path only needs an ENS reverse lookup after the initial resolution and runs it sequentially. The ENS and username paths require an extra initial call and may be slower than the address path on cache misses.
      operationId: resolve_account
      parameters:
      - name: identifier
        in: path
        description: An ENS name (e.g. vitalik.eth), OpenSea username, or wallet address to resolve
        required: true
        schema:
          type: string
          maxLength: 256
          minLength: 0
        example: vitalik.eth
      responses:
        '200':
          description: Resolved account info
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/AccountResolveResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/portfolio:
    get:
      tags:
      - Account Endpoints
      summary: Get portfolio stats for an account
      description: Get portfolio analytics including total value, NFT/token breakdown, and P&L for a wallet address over a given timeframe.
      operationId: get_portfolio_stats
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: timeframe
        in: query
        description: 'Timeframe for P&L calculation: HOUR, DAY, WEEK, MONTH'
        required: false
        schema:
          type: string
          default: DAY
          description: Timeframe for portfolio analytics queries
          enum:
          - HOUR
          - DAY
          - WEEK
          - MONTH
      responses:
        '200':
          description: Portfolio stats
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PortfolioStatsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/portfolio/history:
    get:
      tags:
      - Account Endpoints
      summary: Get portfolio net worth history for an account
      description: Get net worth time series data for a wallet address over a given timeframe.
      operationId: get_portfolio_history
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: timeframe
        in: query
        description: 'Timeframe for history: HOUR, DAY, WEEK, MONTH'
        required: false
        schema:
          type: string
          default: DAY
          description: Timeframe for portfolio analytics queries
          enum:
          - HOUR
          - DAY
          - WEEK
          - MONTH
      responses:
        '200':
          description: Portfolio history
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PortfolioHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/offers_received:
    get:
      tags:
      - Account Endpoints
      summary: Get offers received by an account
      description: Get a paginated list of offers received on items owned by a wallet address.
      operationId: get_profile_offers_received
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: after
        in: query
        description: Cursor for pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
          default: 50
      - name: collection_slugs
        in: query
        description: Filter by collection slugs
        required: false
        schema:
          type: array
          items:
            type: string
      - name: chains
        in: query
        description: Filter by chains
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
      - name: sort_by
        in: query
        description: Sort by field
        required: false
        schema:
          type: string
          default: START_TIME
          enum:
          - START_TIME
          - TOP_ASSET_OFFER
      - name: sort_direction
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Offers received for account
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OffersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/offers:
    get:
      tags:
      - Account Endpoints
      summary: Get active offers made by an account
      description: Get a paginated list of active offers made by a wallet address.
      operationId: get_profile_offers
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: after
        in: query
        description: Cursor for pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
          default: 50
      - name: collection_slugs
        in: query
        description: Filter by collection slugs
        required: false
        schema:
          type: array
          items:
            type: string
      - name: chains
        in: query
        description: Filter by chains
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
      - name: sort_by
        in: query
        description: Sort by field
        required: false
        schema:
          type: string
          default: START_TIME
          enum:
          - START_TIME
          - END_TIME
      - name: sort_direction
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Active offers for account
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/OffersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/listings:
    get:
      tags:
      - Account Endpoints
      summary: Get active listings for an account
      description: Get a paginated list of active listings created by a wallet address.
      operationId: get_profile_listings
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: after
        in: query
        description: Cursor for pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
          default: 50
      - name: collection_slugs
        in: query
        description: Filter by collection slugs
        required: false
        schema:
          type: array
          items:
            type: string
      - name: chains
        in: query
        description: Filter by chains
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
      - name: sort_by
        in: query
        description: Sort by field
        required: false
        schema:
          type: string
          default: START_TIME
          enum:
          - START_TIME
          - END_TIME
      - name: sort_direction
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: Active listings for account
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ListingsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/favorites:
    get:
      tags:
      - Account Endpoints
      summary: Get items favorited by an account
      description: Get a paginated list of items favorited by a wallet address.
      operationId: get_profile_favorites
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: after
        in: query
        description: Cursor for pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
          default: 50
      - name: sort_by
        in: query
        description: Sort by field
        required: false
        schema:
          type: string
          default: CREATED_DATE
          enum:
          - CREATED_DATE
          - PRICE
          - RARITY
          - LISTING_CREATED_DATE
          - LAST_SALE
      - name: sort_direction
        in: query
        description: Sort direction
        required: false
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      - name: chains
        in: query
        description: Filter by chains
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
          uniqueItems: true
      responses:
        '200':
          description: Favorited items
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/NftListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/account/{address}/collections:
    get:
      tags:
      - Account Endpoints
      summary: Get collections owned by an account
      description: Get a paginated list of collections owned by a wallet address, with ownership data.
      operationId: get_profile_collections
      parameters:
      - name: address
        in: path
        description: The wallet address
        required: true
        schema:
          type: string
        example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
      - name: after
        in: query
        description: Cursor for pagination
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
          default: 50
      - name: chains
        in: query
        description: Filter by chains
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
      responses:
        '200':
          description: Collections owned by account
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ProfileCollectionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    Trait:
      type: object
      properties:
        trait_type:
          type: string
        display_type:
          type: string
        max_value:
          type: string
        value: {}
      required:
      - trait_type
      - value
    ListingPrice:
      type: object
      properties:
        current:
          $ref: '#/components/schemas/Price'
      required:
      - current
    CollectionInner:
      type: object
      properties:
        slug:
          type: string
      required:
      - slug
    PortfolioHistoryResponse:
      type: object
      description: Net worth time series data
      properties:
        data_points:
          type: array
          description: Time series data points
          items:
            $ref: '#/components/schemas/PortfolioHistoryDataPoint'
        timeframe:
          type: string
          description: The queried timeframe
          example: WEEK
      required:
      - data_points
      - timeframe
    PortfolioStatsResponse:
      type: object
      description: Portfolio stats including total value, P&L, and asset breakdown
      properties:
        total_value_usd:
          type: string
          description: Total portfolio value in USD
          example: 125430.5
        nft_value_usd:
          type: string
          description: NFT portfolio value in USD
          example: 98200
        token_value_usd:
          type: string
          description: Token portfolio value in USD
          example: 27230.5
        pnl_absolute:
          type: string
          description: Absolute P&L in USD over the timeframe
          example: '+1250.00'
        pnl_percentage:
          type: string
          description: Percentage P&L over the timeframe
          example: '+1.01'
        timeframe:
          type: string
          description: The queried timeframe
          example: WEEK
      required:
      - nft_value_usd
      - timeframe
      - token_value_usd
      - total_value_usd
    AccountResolveResponse:
      type: object
      description: Resolved account info
      properties:
        address:
          type: string
          description: The resolved wallet address
          example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
        username:
          type: string
          description: OpenSea username, if available
        ens_name:
          type: string
          description: Primary ENS name, if available
          example: vitalik.eth
      required:
      - address
    SocialMediaAccount:
      type: object
      properties:
        platform:
          type: string
        username:
          type: string
      required:
      - platform
      - username
    Parameters:
      type: object
      properties:
        offerer:
          type: string
        offer:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        consideration:
          type: array
          items:
            $ref: '#/components/schemas/ConsiderationItem'
        startTime:
          type: string
        endTime:
          type: string
        orderType:
          type: integer
          format: int32
        zone:
          type: string
        zoneHash:
          type: string
        salt:
          type: string
        conduitKey:
          type: string
        totalOriginalConsiderationItems:
          type: integer
          format: int32
        counter:
          type: integer
      required:
      - conduitKey
      - consideration
      - counter
      - endTime
      - offer
      - offerer
      - orderType
      - salt
      - startTime
      - totalOriginalConsiderationItems
      - zone
      - zoneHash
    AccountResponse:
      type: object
      properties:
        address:
          type: string
        username:
          type: string
        profile_image_url:
          type: string
        banner_image_url:
          type: string
        website:
          type: string
        social_media_accounts:
          type: array
          items:
            $ref: '#/components/schemas/SocialMediaAccount'
        bio:
          type: string
        joined_date:
          type: string
          format: date-time
      required:
      - address
      - bio
      - joined_date
      - social_media_accounts
    Item:
      type: object
      properties:
        itemType:
          type: integer
          format: int32
        token:
          type: string
        identifierOrCriteria:
          type: string
        startAmount:
          type: string
        endAmount:
          type: string
      required:
      - endAmount
      - identifierOrCriteria
      - itemType
      - startAmount
      - token
    ListingOrOffer: {}
    OrderAsset:
      type: object
      properties:
        identifier:
          type: string
        contract:
          type: string
      required:
      - contract
    NumericTraitData:
      type: object
      properties:
        type:
          type: string
        min:
          type: number
          format: float
        max:
          type: number
          format: float
      required:
      - type
    Contract:
      type: object
      properties:
        address:
          type: string
        chain:
          type: string
      required:
      - address
      - chain
    Price:
      type: object
      properties:
        currency:
          type: string
        decimals:
          type: integer
          format: int32
        value:
          type: string
      required:
      - currency
      - decimals
      - value
    ProfileCollectionResponse:
      type: object
      properties:
        collection:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        banner_image_url:
          type: string
        owner:
          type: string
        safelist_status:
          type: string
        category:
          type: string
        is_disabled:
          type: boolean
        is_nsfw:
          type: boolean
        trait_offers_enabled:
          type: boolean
        collection_offers_enabled:
          type: boolean
        opensea_url:
          type: string
        project_url:
          type: string
        wiki_url:
          type: string
        discord_url:
          type: string
        telegram_url:
          type: string
        twitter_username:
          type: string
        instagram_username:
          type: string
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/Contract'
        item_count:
          type: integer
          format: int32
        total_quantity:
          type: integer
          format: int32
        usd_value:
          type: number
          format: double
      required:
      - collection
      - collection_offers_enabled
      - contracts
      - is_disabled
      - is_nsfw
      - item_count
      - name
      - opensea_url
      - safelist_status
      - total_quantity
      - trait_offers_enabled
    Offer:
      allOf:
      - $ref: '#/components/schemas/ListingOrOffer'
      - type: object
        properties:
          order_hash:
            type: string
          chain:
            type: string
          protocol_data:
            $ref: '#/components/schemas/ProtocolData'
          protocol_address:
            type: string
          asset:
            $ref: '#/components/schemas/OrderAsset'
          remaining_quantity:
            type: integer
            format: int64
          order_created_at:
            type: integer
            format: int64
          criteria:
            $ref: '#/components/schemas/Criteria'
          price:
            $ref: '#/components/schemas/Price'
          status:
            type: string
            enum:
            - ACTIVE
            - INACTIVE
            - FULFILLED
            - EXPIRED
            - CANCELLED
      required:
      - chain
      - order_hash
      - price
      - remaining_quantity
      - status
    Criteria:
      type: object
      properties:
        collection:
          $ref: '#/components/schemas/CollectionInner'
        contract:
          $ref: '#/components/schemas/ContractInner'
        traits:
          type: array
          items:
            $ref: '#/components/schemas/TraitData'
        numeric_traits:
          type: array
          items:
            $ref: '#/components/schemas/NumericTraitData'
        encoded_token_ids:
          type: string
    NftListResponse:
      type: object
      properties:
        nfts:
          type: array
          items:
            $ref: '#/components/schemas/Nft'
        next:
          type: string
      required:
      - nfts
    ListingsResponse:
      type: object
      properties:
        listings:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
        next:
          type: string
      required:
      - listings
    TraitData:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
      required:
      - type
      - value
    ProfileCollectionsResponse:
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/ProfileCollectionResponse'
        next:
          type: string
      required:
      - collections
    ChainIdentifier:
      type: string
      default: ethereum
      description: Blockchain chain identifier. Use the chain slug (e.g., 'ethereum', 'polygon', 'arbitrum', 'optimism', 'base')
      enum:
      - blast
      - base
      - ethereum
      - zora
      - arbitrum
      - sei
      - avalanche
      - polygon
      - optimism
      - ape_chain
      - flow
      - b3
      - soneium
      - ronin
      - bera_chain
      - solana
      - shape
      - unichain
      - gunzilla
      - abstract
      - animechain
      - hyperevm
      - somnia
      - monad
      - hyperliquid
      - megaeth
      - ink
      example: ethereum
    Nft:
      type: object
      properties:
        identifier:
          type: string
        collection:
          type: string
        contract:
          type: string
        token_standard:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        display_image_url:
          type: string
        display_animation_url:
          type: string
        metadata_url:
          type: string
        opensea_url:
          type: string
        updated_at:
          type: string
        is_disabled:
          type: boolean
        is_nsfw:
          type: boolean
        original_image_url:
          type: string
        original_animation_url:
          type: string
        traits:
          type: array
          items:
            $ref: '#/components/schemas/Trait'
      required:
      - collection
      - contract
      - identifier
      - is_disabled
      - is_nsfw
      - opensea_url
      - token_standard
      - traits
      - updated_at
    ConsiderationItem:
      type: object
      properties:
        itemType:
          type: integer
          format: int32
        token:
          type: string
        identifierOrCriteria:
          type: string
        startAmount:
          type: string
        endAmount:
          type: string
        recipient:
          type: string
      required:
      - endAmount
      - identifierOrCriteria
      - itemType
      - recipient
      - startAmount
      - token
    ContractInner:
      type: object
      properties:
        address:
          type: string
      required:
      - address
    PortfolioHistoryDataPoint:
      type: object
      description: A single net worth data point
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the data point
          example: '2026-04-28T00:00:00Z'
        value_usd:
          type: string
          description: Total portfolio value in USD
          example: 124180
        token_value_usd:
          type: string
          description: Token value in USD
          example: 26000
        nft_value_usd:
          type: string
          description: NFT value in USD
          example: 98180
      required:
      - nft_value_usd
      - timestamp
      - token_value_usd
      - value_usd
    ProtocolData:
      type: object
      properties:
        parameters:
          $ref: '#/components/schemas/Parameters'
        signature:
          type: string
      required:
      - parameters
    OffersResponse:
      type: object
      properties:
        offers:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
        next:
          type: string
      required:
      - offers
    Listing:
      allOf:
      - $ref: '#/components/schemas/ListingOrOffer'
      - type: object
        properties:
          order_hash:
            type: string
          chain:
            type: string
          protocol_data:
            $ref: '#/components/schemas/ProtocolData'
          protocol_address:
            type: string
          asset:
            $ref: '#/components/schemas/OrderAsset'
          remaining_quantity:
            type: integer
            format: int64
          order_created_at:
            type: integer
            format: int64
          price:
            $ref: '#/components/schemas/ListingPrice'
          type:
            type: string
          status:
            type: string
            enum:
            - ACTIVE
            - INACTIVE
            - FULFILLED
            - EXPIRED
            - CANCELLED
      required:
      - chain
      - order_hash
      - price
      - remaining_quantity
      - status
      - type
  responses:
    NotFound:
      description: Resource not found
    BadRequest:
      description: For error reasons, review the response data.
    InternalError:
      description: Internal server error. Please open a support ticket so OpenSea can investigate.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key required for authentication
      name: x-api-key
      in: header
x-tagGroups:
- name: Data & Discovery
  tags:
  - Chain Endpoints
  - Account Endpoints
  - Collection Endpoints
  - NFT Endpoints
  - Contract Endpoints
  - Token Endpoints
  - Search Endpoints
- name: Marketplace & Trading
  tags:
  - Listing Endpoints
  - Offer Endpoints
  - Order Endpoints
  - Swap Endpoints
  - Drops Endpoints
- name: Analytics & Events
  tags:
  - Analytics Endpoints
- name: Tools [Beta]
  tags:
  - Tool Endpoints [Beta]
- name: Transactions
  tags:
  - Transaction Endpoints