Raster GraphQL API

Private alpha GraphQL API. We're starting simple and minimal, and adding features slowly and on request — please reach out if you'd like to see changes.

API Endpoints

https://api.raster.art/graphql

Version

0.1.0

Queries

`address`

Description

Resolve a wallet address. Always returns an Address for any well-formed address; profile and ownership are populated only when such data exists.

Response

Returns an Address

Arguments

Name	Description
`address` - `String!`

Example

Query

query address($address: String!) {
  address(address: $address) {
    address
    profile {
      ...CollectorFragment
    }
    tokensOwned {
      ...TokenOwnershipConnectionFragment
    }
  }
}

Variables

{"address": "0xdf9396b3600583c3dc1e67d5c963f0c4e230680e"}

Response

{
  "data": {
    "address": {
      "address": "0xdf9396b3600583c3dc1e67d5c963f0c4e230680e",
      "profile": Collector,
      "tokensOwned": TokenOwnershipConnection
    }
  }
}

Queries

`artist`

Description

Look up an artist by its opaque id.

Response

Returns an Artist

Arguments

Name	Description
`id` - `ID!`

Example

Query

query artist($id: ID!) {
  artist(id: $id) {
    id
    name
    slug
    addresses
    artworks {
      ...ArtworkConnectionFragment
    }
  }
}

Variables

{"id": "8231"}

Response

{
  "data": {
    "artist": {
      "id": "8231",
      "name": "Michael Connolly",
      "slug": "michael-connolly",
      "addresses": ["0xf92bb2215684c353b4009395061ee7652883c365"],
      "artworks": ArtworkConnection
    }
  }
}

Queries

`artistBySlug`

Description

Look up an artist by its URL slug.

Response

Returns an Artist

Arguments

Name	Description
`slug` - `String!`

Example

Query

query artistBySlug($slug: String!) {
  artistBySlug(slug: $slug) {
    id
    name
    slug
    addresses
    artworks {
      ...ArtworkConnectionFragment
    }
  }
}

Variables

{"slug": "divisions-by-michael-connolly"}

Response

{
  "data": {
    "artistBySlug": {
      "id": "8231",
      "name": "Michael Connolly",
      "slug": "michael-connolly",
      "addresses": ["0xf92bb2215684c353b4009395061ee7652883c365"],
      "artworks": ArtworkConnection
    }
  }
}

Queries

`artwork`

Description

Look up an artwork by its opaque id.

Response

Returns an Artwork

Arguments

Name	Description
`id` - `ID!`

Example

Query

query artwork($id: ID!) {
  artwork(id: $id) {
    id
    slug
    title
    description
    artists {
      ...ArtistFragment
    }
    media {
      ...MediaFragment
    }
    tokens {
      ...TokenConnectionFragment
    }
  }
}

Variables

{"id": "8231"}

Response

{
  "data": {
    "artwork": {
      "id": "8231",
      "slug": "divisions-by-michael-connolly",
      "title": "Divisions",
      "description": "Divisions creates playful abstract compositions that can go all the way up to eleven.",
      "artists": [Artist],
      "media": Media,
      "tokens": TokenConnection
    }
  }
}

Queries

`artworkBySlug`

Description

Look up an artwork by its URL slug.

Response

Returns an Artwork

Arguments

Name	Description
`slug` - `String!`

Example

Query

query artworkBySlug($slug: String!) {
  artworkBySlug(slug: $slug) {
    id
    slug
    title
    description
    artists {
      ...ArtistFragment
    }
    media {
      ...MediaFragment
    }
    tokens {
      ...TokenConnectionFragment
    }
  }
}

Variables

{"slug": "divisions-by-michael-connolly"}

Response

{
  "data": {
    "artworkBySlug": {
      "id": "8231",
      "slug": "divisions-by-michael-connolly",
      "title": "Divisions",
      "description": "Divisions creates playful abstract compositions that can go all the way up to eleven.",
      "artists": [Artist],
      "media": Media,
      "tokens": TokenConnection
    }
  }
}

Queries

`token`

Description

Look up a token by its opaque id.

Response

Returns a Token

Arguments

Name	Description
`id` - `ID!`

Example

Query

query token($id: ID!) {
  token(id: $id) {
    id
    chainId
    contractAddress
    tokenId
    name
    description
    media {
      ...MediaFragment
    }
    artworks {
      ...ArtworkFragment
    }
    artists {
      ...ArtistFragment
    }
    owners {
      ...TokenOwnershipConnectionFragment
    }
  }
}

Variables

{"id": "8231"}

Response

{
  "data": {
    "token": {
      "id": "8231",
      "chainId": "eip155:1",
      "contractAddress": "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270",
      "tokenId": "108000144",
      "name": "Divisions #144",
      "description": "Divisions creates playful abstract compositions that can go all the way up to eleven.",
      "media": Media,
      "artworks": [Artwork],
      "artists": [Artist],
      "owners": TokenOwnershipConnection
    }
  }
}

Queries

`tokenByRef`

Description

Look up a token by its on-chain reference (chain, contract, token id).

Response

Returns a Token

Arguments

Name	Description
`ref` - `TokenRefInput!`

Example

Query

query tokenByRef($ref: TokenRefInput!) {
  tokenByRef(ref: $ref) {
    id
    chainId
    contractAddress
    tokenId
    name
    description
    media {
      ...MediaFragment
    }
    artworks {
      ...ArtworkFragment
    }
    artists {
      ...ArtistFragment
    }
    owners {
      ...TokenOwnershipConnectionFragment
    }
  }
}

Variables

{"ref": TokenRefInput}

Response

{
  "data": {
    "tokenByRef": {
      "id": "8231",
      "chainId": "eip155:1",
      "contractAddress": "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270",
      "tokenId": "108000144",
      "name": "Divisions #144",
      "description": "Divisions creates playful abstract compositions that can go all the way up to eleven.",
      "media": Media,
      "artworks": [Artwork],
      "artists": [Artist],
      "owners": TokenOwnershipConnection
    }
  }
}

Types

Address

Description

A wallet address and anything publicly known about it.

Fields

Field Name	Description
`address` - `String!`	The wallet address.
`profile` - `Collector`	The public collector profile linked to this address, if any.
`tokensOwned` - `TokenOwnershipConnection!`	Tokens held by this address, newest acquisition first. Paginate with `first`/`after`.
Arguments `first` - `Int` `after` - `String`

Example

{
  "address": "0xdf9396b3600583c3dc1e67d5c963f0c4e230680e",
  "profile": Collector,
  "tokensOwned": TokenOwnershipConnection
}

Types

Artist

Description

A creator credited on artworks and/or tokens.

Fields

Field Name	Description
`id` - `ID!`
`name` - `String`	Display name.
`slug` - `String`	URL slug.
`addresses` - `[String!]!`	On-chain addresses attributed to this artist.
`artworks` - `ArtworkConnection!`	Public artworks crediting this artist, newest mint first. Paginate with `first`/`after`.
Arguments `first` - `Int` `after` - `String`

Example

{
  "id": "8231",
  "name": "Michael Connolly",
  "slug": "michael-connolly",
  "addresses": ["0xf92bb2215684c353b4009395061ee7652883c365"],
  "artworks": ArtworkConnection
}

Types

Artwork

Description

A work, backed by one or more on-chain tokens.

Fields

Field Name	Description
`id` - `ID!`
`slug` - `String`	URL slug.
`title` - `String!`	Title.
`description` - `String!`	Long-form description.
`artists` - `[Artist!]!`	Verified artist credits for this artwork.
`media` - `Media`	Preview and content media, taken from the artwork's cover token.
`tokens` - `TokenConnection!`	The artwork's tokens, ordered by mint index. Paginate with `first`/`after`.
Arguments `first` - `Int` `after` - `String`

Example

{
  "id": "8231",
  "slug": "divisions-by-michael-connolly",
  "title": "Divisions",
  "description": "Divisions creates playful abstract compositions that can go all the way up to eleven.",
  "artists": [Artist],
  "media": Media,
  "tokens": TokenConnection
}

Types

ArtworkConnection

Description

A page of artworks.

Fields

Field Name	Description
`nodes` - `[Artwork!]!`
`pageInfo` - `PageInfo!`

Example

{
  "nodes": [Artwork],
  "pageInfo": PageInfo
}

Types

BigInt

Description

An integer that may exceed 32/64 bits (e.g. an NFT token id), serialized as a decimal string to avoid precision loss. Accepts an integer or an integer string as input.

Example

"108000144"

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example

true

Types

Collector

Description

A public collector profile.

Fields

Field Name	Description
`id` - `ID!`
`username` - `String`	Chosen username.
`slug` - `String`	URL slug.
`addresses` - `[String!]!`	Verified, public addresses linked to this profile.

Example

{
  "id": "8231",
  "username": "Le Random",
  "slug": "le-random",
  "addresses": ["0xdf9396b3600583c3dc1e67d5c963f0c4e230680e"]
}

Types

DateTime

Description

ISO-8601 / RFC-3339 timestamp in UTC, e.g. 2024-01-01T00:00:00.000Z.

Example

"2023-08-27T11:43:23.000Z"

Types

Dimensions

Description

Pixel dimensions of a media asset.

Fields

Field Name	Description
`width` - `Int!`
`height` - `Int!`

Example

{"width": 1714, "height": 2400}

Types

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example

"8231"

Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example

Types

Media

Description

Preview and full-content media for an artwork or token.

Fields

Field Name	Description
`previewHash` - `String`	Hash of the preview image, used to build a preview URL.
`previewType` - `String`	MIME type of the preview.
`contentUrl` - `String`	URL of the full content.
`contentType` - `String`	MIME type of the full content.
`contentSize` - `Int`	Size of the full content, in bytes.
`dimensions` - `Dimensions`	Intrinsic pixel dimensions, when known.

Example

{
  "previewHash": "f1882baccbad286c0711ed8169778f6068fc853bb126b543561f2be7fdf9357d",
  "previewType": "image/png",
  "contentUrl": "https://media.artblocks.io/108000144.png",
  "contentType": "image/png",
  "contentSize": 107698,
  "dimensions": Dimensions
}

Types

PageInfo

Description

Cursor-pagination metadata for a connection.

Fields

Field Name	Description
`hasNextPage` - `Boolean!`	Whether more results follow the current page.
`endCursor` - `String`	Opaque cursor of the last node; pass as `after` to fetch the next page.

Example

{"hasNextPage": true, "endCursor": "eyJpZCI6MTA4MDAwMTQ0fQ"}

Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example

"example"

Types

Token

Description

A single on-chain token (NFT).

Fields

Field Name	Description
`id` - `ID!`
`chainId` - `String!`	CAIP-2 chain id, e.g. `eip155:1`.
`contractAddress` - `String`	Contract address; null on chains without contracts (e.g. Bitcoin).
`tokenId` - `BigInt!`	The token's on-chain id.
`name` - `String`	Token name, from token metadata.
`description` - `String`	Token description, from token metadata.
`media` - `Media`	Preview and content media for this token.
`artworks` - `[Artwork!]!`	Artworks this token belongs to.
`artists` - `[Artist!]!`	Artists credited on this token, falling back to its artworks' credits when it has none.
`owners` - `TokenOwnershipConnection!`	Current holders, largest holding first; burn/system addresses excluded. Paginate with `first`/`after`.
Arguments `first` - `Int` `after` - `String`

Example

{
  "id": "8231",
  "chainId": "eip155:1",
  "contractAddress": "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270",
  "tokenId": "108000144",
  "name": "Divisions #144",
  "description": "Divisions creates playful abstract compositions that can go all the way up to eleven.",
  "media": Media,
  "artworks": [Artwork],
  "artists": [Artist],
  "owners": TokenOwnershipConnection
}

Types

TokenConnection

Description

A page of tokens.

Fields

Field Name	Description
`nodes` - `[Token!]!`
`pageInfo` - `PageInfo!`

Example

{
  "nodes": [Token],
  "pageInfo": PageInfo
}

Types

TokenOwnership

Description

A holding: an address's ownership of a token.

Fields

Field Name	Description
`address` - `Address!`	The holder.
`token` - `Token!`	The held token.
`quantity` - `BigInt!`	Number of units held (1 for a non-fungible token).
`lastAcquiredAt` - `DateTime`	When this holding was last updated on-chain (its most recent acquisition).

Example

{
  "address": "0xdf9396b3600583c3dc1e67d5c963f0c4e230680e",
  "token": Token,
  "quantity": "1",
  "lastAcquiredAt": "2023-08-27T11:43:23.000Z"
}

Types

TokenOwnershipConnection

Description

A page of token holdings.

Fields

Field Name	Description
`nodes` - `[TokenOwnership!]!`
`pageInfo` - `PageInfo!`

Example

{
  "nodes": [TokenOwnership],
  "pageInfo": PageInfo
}

Types

TokenRefInput

Description

On-chain reference that identifies a single token.

Fields

Input Field	Description
`chainId` - `String!`	CAIP-2 chain id, e.g. `eip155:1`.
`contractAddress` - `String`	Contract address; omit on chains without contracts (e.g. Bitcoin).
`tokenId` - `BigInt!`	The token's on-chain id.

Example

{
  "chainId": "eip155:1",
  "contractAddress": "0xa7d8d9ef8d8ce8992df33d8b8cf4aebabd5bd270",
  "tokenId": "108000144"
}

Documentation by Anvil SpectaQL

Raster GraphQL API

API Endpoints

Version

Queries

address

Description

Response

Arguments

Example

Query

Variables

Response

artist

Description

Response

Arguments

Example

Query

Variables

Response

artistBySlug

Description

Response

Arguments

Example

Query

Variables

Response

artwork

Description

Response

Arguments

Example

Query

Variables

Response

artworkBySlug

Description

Response

Arguments

Example

Query

Variables

Response

token

Description

Response

Arguments

Example

Query

Variables

Response

tokenByRef

Description

Response

Arguments

Example

Query

Variables

Response

Types

Address

Description

Fields

Arguments

first - Int

after - String

Example

Artist

Description

Fields

Arguments

first - Int

after - String

Example

Artwork

Description

Fields

Arguments

first - Int

`address`

`artist`

`artistBySlug`

`artwork`

`artworkBySlug`

`token`

`tokenByRef`

`first` - `Int`

`after` - `String`

`first` - `Int`

`after` - `String`

`first` - `Int`

`after` - `String`

`first` - `Int`

`after` - `String`