Skip to contents

Quickstart

Source: vignettes/quickstart.qmd

Overview

This quickstart guide gets you productive with artopensea in minutes. You’ll learn how to configure the package, make basic API calls, and integrate OpenSea data into your R workflows.

Prerequisites

  • R 4.1.0 or higher
  • An OpenSea API key (free at https://docs.opensea.io/reference/api-keys)

Configuration

Set Your API Key

Configure the ART_OPENSEA_KEY environment variable before loading the package:

library(artopensea)

# Set API key for this session
Sys.setenv(ART_OPENSEA_KEY = "your-api-key-here")

Persistent Configuration

For permanent configuration, add to your .Renviron file:

# Edit .Renviron
usethis::edit_r_environ()

# Add this line:
ART_OPENSEA_KEY=your-api-key-here

After saving, restart R for changes to take effect.

Basic API Calls

Fetch Account Information

Retrieve account profile data by wallet address:

library(jsonlite)

# Get account metadata
account_json <- get_os_account("0xa16DCcD55139D5eF5B5Ff776553ef080EB6258fc")

# Parse JSON response
account <- fromJSON(account_json)

# Access account details
account$username
account$bio
account$profile_image_url

What you get: Account username, bio, profile image, social links, and collection counts.

Fetch Individual NFT Metadata

Retrieve detailed metadata for a specific NFT:

# Fetch NFT data
nft_json <- get_os_nft(
    id = 2,
    chain = "matic",
    contract = "0x6444522C5aD44285b7856dd3336D09Fb939865F1"
)

nft <- fromJSON(nft_json)

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

What you get: NFT name, description, image URL, metadata URI, traits/attributes, creator info, and ownership data.

List Account’s NFTs

Retrieve all NFTs owned by an account on a specific chain:

# Fetch NFT portfolio
nfts_json <- get_os_account_nfts(
    account = "0xa16DCcD55139D5eF5B5Ff776553ef080EB6258fc",
    chain = "matic"
)

nfts <- fromJSON(nfts_json)

# Access NFT array (up to 200 items)
nfts$nfts

What you get: Array of NFT objects (max 200 per request). Each object contains the same metadata as get_os_nft().

Pagination: If the account owns >200 NFTs, the response includes a next cursor for fetching additional pages.

Discover Creator Collections

Find all collections created by a specific OpenSea user:

# Fetch creator's collections
collections_json <- get_os_collections(
    creator = "b_fatemi_art",
    chain = "matic"
)

collections <- fromJSON(collections_json)

# Access collections array
collections$collections

What you get: Array of collection objects (max 100 per request) with collection name, contract address, creation date, and statistics.

URL Utilities

Parse OpenSea URLs

Extract chain, contract, and token ID from OpenSea URLs:

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

parts <- parseOpenseaURL(url)

parts$chain      # "matic"
parts$contract   # "0x6444522C5aD44285b7856dd3336D09Fb939865F1"
parts$id         # "2"

Use case: Process user-provided URLs to extract identifiers for API calls.

# Use parsed components to fetch NFT
nft_json <- get_os_nft(
    id = parts$id,
    chain = parts$chain,
    contract = parts$contract
)

Build OpenSea URLs

Generate OpenSea marketplace URLs from components:

url <- buildOpenseaURL(
    chain = "matic",
    contract = "0x6444522C5aD44285b7856dd3336D09Fb939865F1",
    id = 2
)

print(url)
#> [1] "https://opensea.io/assets/matic/0x6444522C5aD44285b7856dd3336D09Fb939865F1/2"

Use case: Create marketplace links from database-stored NFT metadata.

Shiny Integration

Add OpenSea Badge Widget

Display the official OpenSea badge in Shiny apps:

library(shiny)

ui <- fluidPage(
    titlePanel("NFT Gallery"),

    # OpenSea badge
    uiOutput("opensea_badge")
)

server <- function(input, output, session) {
    output$opensea_badge <- renderUI({
        getOpenseaBadge(
            contract = "0x6444522C5aD44285b7856dd3336D09Fb939865F1",
            id = 2,
            chain = "matic",
            width = "150px"  # Customize badge size
        )
    })
}

shinyApp(ui, server)

The badge is a clickable image that links to the NFT’s OpenSea marketplace page and opens in a new tab.

Customize Badge Size

Control badge display size with the width parameter:

# Small badge
getOpenseaBadge(contract, id, chain, width = "100px")

# Large badge
getOpenseaBadge(contract, id, chain, width = "250px")

# Responsive width
getOpenseaBadge(contract, id, chain, width = "100%")

Working with Responses

Parse JSON Strings

All API functions return JSON strings. Use jsonlite::fromJSON() to parse:

library(jsonlite)

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

# Access nested fields
parsed$nft$name
parsed$nft$image_url

Extract Specific Fields 

# Get just the NFT name
nft_name <- fromJSON(nft_json)$nft$name

# Get all trait types
traits <- fromJSON(nft_json)$nft$traits
trait_types <- traits$trait_type

Convert to data.table

For analysis with data.table:

library(data.table)

# Parse NFT portfolio
nfts <- fromJSON(nfts_json)

# Convert to data.table
nfts_dt <- as.data.table(nfts$nfts)

# Analyze
nfts_dt[, .N, by = collection]

Common Patterns

Batch Fetch Multiple NFTs

Fetch metadata for multiple NFTs in the same collection:

contract <- "0x6444522C5aD44285b7856dd3336D09Fb939865F1"
chain <- "matic"
token_ids <- c(1, 2, 3, 4, 5)

# Fetch each NFT
nfts_list <- lapply(token_ids, function(id) {
    json <- get_os_nft(id, chain, contract)
    fromJSON(json)
})

# Extract names
nft_names <- sapply(nfts_list, function(nft) nft$nft$name)

Important: Add delays between requests to avoid rate limiting (see Advanced Workflow vignette).

Check NFT Ownership

Verify if an account owns a specific NFT:

# Fetch account's NFTs
nfts_json <- get_os_account_nfts(account, chain)
nfts <- fromJSON(nfts_json)

# Check if specific NFT is in portfolio
target_contract <- "0x6444522C5aD44285b7856dd3336D09Fb939865F1"
target_id <- "2"

owned <- any(
    nfts$nfts$contract == target_contract &
    nfts$nfts$identifier == target_id
)

if (owned) {
    message("Account owns this NFT")
} else {
    message("Account does not own this NFT")
}

Display NFT Image in Shiny

Fetch and display NFT images:

library(shiny)

ui <- fluidPage(
    titlePanel("NFT Display"),
    uiOutput("nft_image")
)

server <- function(input, output, session) {
    output$nft_image <- renderUI({
        nft_json <- get_os_nft(
            id = 2,
            chain = "matic",
            contract = "0x6444522C5aD44285b7856dd3336D09Fb939865F1"
        )

        nft <- fromJSON(nft_json)

        tags$div(
            h3(nft$nft$name),
            img(src = nft$nft$image_url, width = "400px"),
            p(nft$nft$description)
        )
    })
}

Supported Chains

artopensea supports multiple blockchain networks:

Chain Identifier Description
Ethereum "ethereum" Ethereum mainnet
Polygon "matic" Polygon (formerly Matic)
Arbitrum "arbitrum" Arbitrum One
Optimism "optimism" Optimism mainnet
Base "base" Base (Coinbase L2)
Avalanche "avalanche" Avalanche C-Chain

Use these identifiers in the chain parameter for all API functions.

Error Handling

Missing API Key 

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

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

Invalid Parameters 

Error: HTTP 404 Not Found

Solution: Verify contract address, token ID, and chain are correct. Test the URL in a browser first.

Network Timeout 

Error: Timeout was reached

Solution: All functions have a 5-second timeout. Retry the request or check your network connection.

Next Steps

Additional Resources