Introduction
Welcome to the SuperRare Public API. This API provides access to SuperRare's NFT ecosystem data, including NFTs, collections, sales, auctions, and user information. The API is GraphQL-based, offering flexible querying capabilities.
Table of Contents
Support
Getting Started:
Base URL
Playground:
<https://api.superrare.com/graphql>
Core Queries
Get NFT
Query NFTs with filtering options.
Query
query GetNfts {
getNfts(
filter: {
contractAddress: { equals: "0x41a322b28d0ff354040e2cbc676f0320d8c8850d" }
},
pagination: { take: 1 }
) {
nfts {
contractAddress
tokenId
universalTokenId
creator {
defaultAddress
profile {
username
}
}
owner {
defaultAddress
}
metadata {
name
proxyMedia {
image {
small
medium
full
}
}
}
state {
auction {
currentBid
minimumBid
auctionState
}
listing {
amount
currency
}
}
}
pagination {
hasNextPage
total
}
}
}
Example Response
{
"data": {
"getNfts": {
"nfts": [
{
"contractAddress": "0x41A322b28D0fF354040e2CbC676F0320d8c8850d",
"tokenId": 4006,
"universalTokenId": "1-0x41a322b28d0ff354040e2cbc676f0320d8c8850d-4006",
"creator": {
"defaultAddress": "0xBFC9f6C46715755E2ee8b01f20AB36D22cB4Ad4f",
"profile": {
"username": "bigcomic"
}
},
"owner": {
"defaultAddress": "0x508B0972Adc005d174774BcBEBc2F49bF0A7d076"
},
"metadata": {
"name": "♥️",
"proxyMedia": {
"image": {
"small": "https://pixura.imgix.net/https%3A%2F%2Fstorage.googleapis.com%2Fsr_prod_artworks_bucket%2Fasset%252F0496f4106bc7a54be00c3a36a6526c00f5c6597c3b42723836d8f74e901a2cc5.gif?ixlib=js-3.8.0&width=150&height=150&fm=avif&fit=crop&video=false&name=IMAGE_SMALL&auto=compress&s=b0e8813e78c714d07a4a9ca746e92f5a",
"medium": "https://pixura.imgix.net/https%3A%2F%2Fstorage.googleapis.com%2Fsr_prod_artworks_bucket%2Fasset%252F0496f4106bc7a54be00c3a36a6526c00f5c6597c3b42723836d8f74e901a2cc5.gif?ixlib=js-3.8.0&width=550&height=550&fm=avif&fit=crop&video=false&name=ImageMedium&auto=compress&s=53c92670eddc8aed61c51ff97c45fa75",
"full": "https://storage.googleapis.com/sr_prod_artworks_bucket/asset%2F0496f4106bc7a54be00c3a36a6526c00f5c6597c3b42723836d8f74e901a2cc5.gif"
}
}
},
"state": {
"auction": null,
"listing": null
}
}
],
"pagination": {
"hasNextPage": true,
"total": 4091
}
}
}
}
Get NFT Events
Retrieve NFT events such as sales, transfers, and auctions with filtering options.
Query with Variables
query GetNftEvents($paginationSettings: PaginationInput!) {
getNftEvents(
filter: {},
pagination: $paginationSettings
) {
events {
eventType
createdAt
nft {
universalTokenId
contractAddress
tokenId
metadata {
name
}
}
agent {
defaultAddress
profile {
username
}
}
patient {
defaultAddress
profile {
username
}
}
}
pagination {
total
hasNextPage
}
}
}
Query Variables Example
{
"paginationSettings": {
"take": 1,
"sortBy": "createdAt",
"order": "desc"
}
}Example Response
{
"data": {
"getNftEvents": {
"events": [
{
"eventType": "TRANSFER_NFT",
"createdAt": "2025-02-27T18:53:47.000Z",
"nft": {
"universalTokenId": "1-0xb932a70a57673d89f4acffbe830e8ed7f75fb9e0-43694",
"contractAddress": "0xb932a70A57673d89f4acfFBE830E8ed7f75Fb9e0",
"tokenId": 43694,
"metadata": {
"name": "Takeshi: The Crypto Crusader"
}
},
"agent": {
"defaultAddress": "0x5124B17B55f4c8f4395a06A461c5109cF3d5f7eB",
"profile": {
"username": "richardnadler"
}
},
"patient": {
"defaultAddress": "0x5d972c305f05757D9F8c80c821469fe41B058558",
"profile": {
"username": null
}
}
}
]
}
}
}
Sample Working Query Examples
Note: The getNftEvents query works best without specifying event type filters. If you need to filter by event type, you may need to filter the results client-side. The agent and patient fields typically represent the actors in the transaction (e.g., buyer and seller).
Here are some sample queries you can use directly with the SuperRare public API (no variables required):
Get NFTs by Contract Address
query GetNftsByContract {
getNfts(
filter: {
contractAddress: { equals: "0x41a322b28d0ff354040e2cbc676f0320d8c8850d" }
},
pagination: { take: 5 }
) {
nfts {
contractAddress
tokenId
universalTokenId
metadata {
name
}
creator {
defaultAddress
}
}
pagination {
hasNextPage
total
}
}
}
Get NFTs by Creator Address
query GetNftsByCreator {
getNfts(
filter: {
creatorAddress: { equals: "0x3B3ee1931Dc30C1957379FAc9aba94D1C48a5405" }
},
pagination: { take: 5 }
) {
nfts {
universalTokenId
contractAddress
tokenId
metadata {
name
proxyMedia {
image {
medium
}
}
}
creator {
profile {
username
}
}
}
pagination {
total
}
}
}
Get NFTs by Owner Address
query GetNftsByOwner {
getNfts(
filter: {
ownerAddress: { equals: "0x7A7C5f389889b5D786a98D8D1BF5f4c7872bE0a5" }
},
pagination: { take: 5 }
) {
nfts {
universalTokenId
contractAddress
tokenId
metadata {
name
proxyMedia {
image {
medium
}
}
}
owner {
profile {
username
}
}
}
pagination {
total
}
}
}
Get NFT Events (Recent Activity)
query GetRecentNftEvents {
getNftEvents(
filter: {},
pagination: { take: 10 }
) {
events {
eventType
createdAt
nft {
universalTokenId
contractAddress
tokenId
metadata {
name
}
}
agent {
defaultAddress
}
patient {
defaultAddress
}
}
pagination {
total
}
}
}
Error Handling
GraphQL errors follow this format:
{
"errors": [
{
"message": "Error description",
"locations": [
{
"line": 2,
"column": 3
}
],
"path": ["field", "subfield"],
"extensions": {
"code": "ERROR_CODE"
}
}
]
}
Common Error Codes
FORBIDDEN: Insufficient permissions
BAD_USER_INPUT: Invalid query parameters
RATE_LIMIT_EXCEEDED: Too many requests
INTERNAL_SERVER_ERROR: Server error
Rate Limits
Tier | Requests/Minute |
Standard | 5 |
Best Practices
Use Pagination
Implement cursor-based pagination for large datasets
Use reasonable page sizes (10-50 items)
Optimize Queries
Request only needed fields
Use fragments for repeated field sets
Batch related queries
Handle Errors
Implement proper error handling
Respect rate limits
Use exponential backoff for retries
Cache Responses
Cache stable data
Respect cache headers
Implement proper cache invalidation
Support
Email: [email protected]