Getting started

This page assumes you’re integrating against NFTX from a TypeScript codebase (Next.js, a worker, a CLI, anything). For the API/subgraph-only path, jump straight to Subgraph recipes.

Prerequisites

Node.js ≥ 20.
A Base RPC URL — mainnet (8453) or Sepolia (84532).
Familiarity with viem.

NFTX ships its own viem-ready ABIs in Frontend/packages/contracts/src/abis. Inside the monorepo, prefer importing from there rather than re-deriving the ABI from Contracts/out/.

1. Install

Add `viem` and the NFTX ABIs

pnpm add viem
# inside the monorepo, also link the workspace package:
pnpm add @nftx/contracts@workspace:*

Point at the right chain

NFTX is currently deployed on Base mainnet (8453) and Base Sepolia (84532). Addresses live in Frontend/packages/config/src/contracts.ts and mirror the on-chain Locker.implementation() / collection registry.

import { base, baseSepolia } from "viem/chains";
import { createPublicClient, http } from "viem";
 
export const client = createPublicClient({
  chain: base,
  transport: http(process.env.BASE_RPC_URL),
});

Read a single collection

The Locker is the canonical entry point. Every other contract derives its state from a (collection, tokenId) pair, so always start by reading the locker.

example.ts

import { lockerAbi } from "@nftx/contracts";
import { NFTX_CONTRACTS } from "@nftx/config";
 
const collection = "0xYourCollectionAddress";
const collectionToken = await client.readContract({
  address: NFTX_CONTRACTS[8453].locker,
  abi: lockerAbi,
  functionName: "collectionToken",
  args: [collection],
});

2. Point at the subgraph

The Envio HyperIndex GraphQL endpoint exposes collections, listings, pool fees, shutdowns, and airdrops. Read Subgraph overview for the entity map; Subgraph recipes has copy-paste queries for the most common FE needs.

curl -X POST $NFTX_GRAPHQL_URL \
  -H 'content-type: application/json' \
  -d '{"query":"{ Collection_aggregate { aggregate { count } } }"}'

3. Pick a journey

Each user journey maps a single FE flow to:

Prerequisites (approvals, paused state, balances).
Inputs.
Contract calls (in order).
A viem code example.
Failure modes (interface errors with reason strings).
Subgraph follow-through (which entities update + a sample query).

Overview Architecture