Skip to contents

Get started with artopensea

Source: vignettes/artopensea.qmd

What is artopensea?

artopensea is an R wrapper for the OpenSea API v2, providing programmatic access to NFT metadata, account information, and collection data from the world’s largest NFT marketplace. The package eliminates the need for direct blockchain node access or complex web3 libraries, offering a simple R-native interface to OpenSea’s REST API.

Key Capabilities

  • NFT Metadata Retrieval: Fetch detailed information about individual NFTs including images, traits, and ownership
  • Account Portfolio Access: List all NFTs owned by any Ethereum address across supported chains
  • Collection Discovery: Find collections by creator username
  • URL Utilities: Parse and construct OpenSea marketplace URLs
  • Shiny Integration: Add official OpenSea badges to your Shiny applications

When to Use artopensea

Use this package when you need to:

  • Build NFT portfolio dashboards in Shiny
  • Verify NFT ownership and authenticity
  • Display NFT metadata in R applications
  • Integrate OpenSea marketplace links into your workflows
  • Analyze NFT collection statistics

This package is NOT for: Trading NFTs, minting NFTs, or blockchain transactions. It provides read-only access to marketplace metadata.

Installation 

# Install from GitHub (requires GITHUB_PAT)
# pak::pkg_install("artalytics/artopensea")

library(artopensea)

Configuration

Before using artopensea, configure your OpenSea API key. Get a free key at https://docs.opensea.io/reference/api-keys

Sys.setenv(ART_OPENSEA_KEY = "your-api-key-here")

For persistent configuration, add this to your .Renviron file:

ART_OPENSEA_KEY=your-api-key-here

Complete Workflow 1: Retrieving and Displaying NFT Data

This workflow demonstrates fetching a specific NFT’s metadata and displaying it with an OpenSea marketplace link.

Step 1: Parse an OpenSea URL

Start with a URL from the OpenSea marketplace. Extract the chain, contract, and token ID:

url <- "https://opensea.io/assets/matic/0x6444522C5aD44285b7856dd3336D09Fb939865F1/2"

nft_parts <- parseOpenseaURL(url)
print(nft_parts)
#> $chain
#> [1] "matic"
#>
#> $contract
#> [1] "0x6444522C5aD44285b7856dd3336D09Fb939865F1"
#>
#> $id
#> [1] "2"

Step 2: Fetch NFT Metadata

Use the extracted components to retrieve full NFT metadata from OpenSea:

nft_json <- get_os_nft(
    id = nft_parts$id,
    chain = nft_parts$chain,
    contract = nft_parts$contract
)

The response is a JSON string. Parse it to access specific fields:

library(jsonlite)

nft_data <- fromJSON(nft_json)

# Access NFT properties
nft_data$nft$name
nft_data$nft$description
nft_data$nft$image_url
nft_data$nft$traits  # data frame of attributes

Step 3: Display in Shiny with OpenSea Badge

Create a Shiny UI that shows the NFT image and links to OpenSea:

library(shiny)

ui <- fluidPage(
    titlePanel("NFT Display"),
    fluidRow(
        column(6,
            h3(nft_data$nft$name),
            img(src = nft_data$nft$image_url, width = "100%"),
            p(nft_data$nft$description)
        ),
        column(6,
            h4("View on OpenSea"),
            getOpenseaBadge(
                contract = nft_parts$contract,
                id = nft_parts$id,
                chain = nft_parts$chain,
                width = "200px"
            )
        )
    )
)

The getOpenseaBadge() function creates a clickable image that links to the NFT’s OpenSea page, opening in a new tab.

Complete Workflow 2: Listing an Account’s NFT Portfolio

This workflow shows how to retrieve and display all NFTs owned by a specific wallet address.

Step 1: Get Account Information

Start by fetching the account profile to display user information:

account_addr <- "0xa16DCcD55139D5eF5B5Ff776553ef080EB6258fc"

account_json <- get_os_account(account_addr)
account_data <- fromJSON(account_json)

# Display account details
account_data$username
account_data$bio

Step 2: List Account NFTs on a Chain

Retrieve all NFTs owned by this account on the Polygon (matic) chain:

nfts_json <- get_os_account_nfts(
    account = account_addr,
    chain = "matic"
)

nfts_data <- fromJSON(nfts_json)

# Access the NFTs array
nfts_data$nfts  # data frame with up to 200 NFTs

Step 3: Build a Portfolio Display

Extract key information for each NFT and create a portfolio table:

library(data.table)

portfolio <- data.table::as.data.table(nfts_data$nfts)

# Select columns for display
portfolio_summary <- portfolio[, .(
    name,
    collection = collection,
    contract = contract,
    token_id = identifier
)]

print(portfolio_summary)

Step 4: Handle Pagination

If the account owns more than 200 NFTs, implement pagination:

# Check if there are more results
if (!is.null(nfts_data[["next"]])) {
    next_cursor <- nfts_data[["next"]]
    # In a real implementation, you would make another request
    # with the cursor parameter (requires manual httr2 request)
    message("More NFTs available. Cursor: ", next_cursor)
}

Note: The OpenSea API returns a maximum of 200 items per request. For accounts with larger portfolios, you’ll need to implement cursor-based pagination using the next field from the response.

Complete Workflow 3: Discovering Creator Collections

This workflow demonstrates finding all collections created by a specific artist.

Step 1: Fetch Collections by Creator

Use the creator’s OpenSea username to find their collections:

collections_json <- get_os_collections(
    creator = "b_fatemi_art",
    chain = "matic"
)

collections_data <- fromJSON(collections_json)

Step 2: Extract Collection Metadata

Parse the response to access collection details:

collections_dt <- data.table::as.data.table(collections_data$collections)

# Key collection information
collections_dt[, .(
    collection_name = collection,
    contract = contracts[[1]]$address,
    created_date,
    total_supply
)]

Generate OpenSea URLs for each collection’s first NFT:

# For each collection, build URL to first NFT (token ID 0)
collections_dt[, opensea_url := buildOpenseaURL(
    chain = "matic",
    contract = contracts[[1]]$address,
    id = 0
)]

print(collections_dt$opensea_url)

Working with JSON Responses

All API functions return JSON strings. Here are common patterns for extracting data:

Parse JSON to R Objects 

library(jsonlite)

# Parse JSON string to R list/data.frame
parsed <- fromJSON(json_string)

# Access nested fields
parsed$nft$name
parsed$nft$traits$trait_type

Extract Specific Fields 

# Get just the image URL
image_url <- fromJSON(nft_json)$nft$image_url

# Get trait names as vector
traits <- fromJSON(nft_json)$nft$traits
trait_names <- traits$trait_type

Convert to data.table for Analysis 

library(data.table)

# Convert traits to data.table
traits_dt <- data.table::as.data.table(
    fromJSON(nft_json)$nft$traits
)

# Filter and analyze
traits_dt[trait_type == "Background", value]

Error Handling and Troubleshooting

Common Errors

API Key Not Set 

Error in ..api_opensea_key() : ART_OPENSEA_KEY environment variable not set

Solution: Set the environment variable as shown in Configuration section above.

Invalid Contract or Token ID 

Error: HTTP 404 Not Found

Solution: Verify the contract address and token ID are correct. Check the OpenSea URL in a browser first.

Rate Limiting

The OpenSea API has rate limits. If you’re making many requests:

# Add delays between requests
for (id in token_ids) {
    nft <- get_os_nft(id, chain, contract)
    Sys.sleep(0.5)  # Wait 500ms between requests
}

Network Timeouts

All functions have a 5-second timeout. If requests fail due to slow networks:

Error: Timeout was reached

Solution: The timeout is hardcoded in the package. For slow connections, you may need to retry the request or use the underlying httr2 functions directly with custom timeout values.

Next Steps

Learn More

Additional Resources