Quickstart

This guide walks you through the full verification flow end-to-end: create a collection, add a unit, attach a test chip, simulate a tap, and verify it. Every step shows both @endstate-sdk/core and curl, so you can follow it either way. The SDK is TypeScript-first with zero runtime dependencies; install it with npm install @endstate-sdk/core and construct the client once:

import { EndstateClient, secretKey } from "@endstate-sdk/core";

const endstate = new EndstateClient({
  apiKey: secretKey(process.env.ENDSTATE_API_KEY),
});

Every /v1/* request includes your API key in the Authorization header - Authorization: Bearer end_sk_.... Keep it server-side only, and never expose it in browser code. See Credentials for the full details on credential types and session tokens.

Create a collection

A collection groups related units under one product line. Create one first - units belong to a collection, and the collection must be active before units can be issued.

const collection = await endstate.collections.create({
  name: "Summer Tee 2026",
});

curl -X POST https://api2.endstate.io/v1/collections \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Tee 2026"
  }'

Response

{
  "id": "8e1a7f50-90ab-4cde-b012-3456789abcde",
  "name": "Summer Tee 2026",
  "external_id": null,
  "redirect_url": null,
  "contract": {
    "status": "deploying",
    "address": "0x1111111111111111111111111111111111111111",
    "chain_id": 84532
  }
}

Single-resource responses return their fields at the top level; list responses wrap their array under a plural key. See Response shape.

The collection is created on your organization’s default network, configured by Endstate at onboarding - no network field needed. You can read it (and the networks enabled for your organization) from Organization settings, and pass chain_id explicitly only to override it.

The collection returns immediately with contract.status: "deploying" - provisioning is asynchronous. Poll GET /v1/collections/{collection_id} until contract.status is "active" before proceeding.

// Waits out provisioning, then returns the active collection.
const active = await endstate.collections.waitUntilActive(collection.id);

curl https://api2.endstate.io/v1/collections/8e1a7f50-90ab-4cde-b012-3456789abcde \
  -H "Authorization: Bearer end_sk_..."

Response

{
  "id": "8e1a7f50-90ab-4cde-b012-3456789abcde",
  "name": "Summer Tee 2026",
  "external_id": null,
  "redirect_url": null,
  "contract": {
    "status": "active",
    "address": "0x1111111111111111111111111111111111111111",
    "chain_id": 84532
  }
}

When contract.status is "active", the collection is ready. Poll on a short interval (one to two seconds) and give up after a reasonable timeout.

Create a unit

A unit is the unique digital record for a single physical item. Create one inside your collection.

const unit = await endstate.units.create({
  collection_id: collection.id,
});

curl -X POST https://api2.endstate.io/v1/units \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "8e1a7f50-90ab-4cde-b012-3456789abcde"
  }'

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": null,
  "name": null,
  "attributes": null,
  "redirect_url": null,
  "created_at": "2026-06-15T10:01:00.000Z",
  "collection": {
    "id": "8e1a7f50-90ab-4cde-b012-3456789abcde",
    "name": "Summer Tee 2026",
    "external_id": null,
    "contract": {
      "address": "0x1111111111111111111111111111111111111111",
      "chain_id": 84532,
      "status": "active"
    },
    "token": {
      "status": "pending",
      "serial": null
    }
  },
  "chips": []
}

The unit starts with collection.token.status: "pending". It moves to "active" (and receives a collection.token.serial) after a chip is paired in the next step.

Create a test chip

A test chip lets you simulate taps without physical hardware. Pass is_test: true and the unit you created.

const chip = await endstate.chips.pair({
  unit_id: unit.id,
  is_test: true,
});

curl -X POST https://api2.endstate.io/v1/chips \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "unit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "is_test": true
  }'

Response

{
  "chip_id": "ABCDEF0123",
  "is_test": true,
  "scan_count": 0,
  "created_at": "2026-06-15T10:02:00.000Z",
  "unit": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": null,
    "name": null,
    "attributes": null,
    "redirect_url": null,
    "created_at": "2026-06-15T10:01:00.000Z",
    "collection": {
      "id": "8e1a7f50-90ab-4cde-b012-3456789abcde",
      "name": "Summer Tee 2026",
      "external_id": null,
      "contract": {
        "address": "0x1111111111111111111111111111111111111111",
        "chain_id": 84532,
        "status": "active"
      },
      "token": {
        "status": "pending",
        "serial": null
      }
    }
  }
}

Note the chip_id - you use it in the next two steps. Pairing a chip also triggers issuance: the unit’s token.status transitions from "pending" to "active" and token.serial is assigned.

Simulate a tap

Real chips produce a one-time e value when tapped. For test chips, POST /v1/test-helpers/taps generates one for you.

const tap = await endstate.testHelpers.createTap({
  chip_id: chip.chip_id,
});

curl -X POST https://api2.endstate.io/v1/test-helpers/taps \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "chip_id": "ABCDEF0123" }'

Response

{
  "chip_id": "ABCDEF0123",
  "e": "C78566198547116F3A715DC1C62AF96F",
  "count": 1
}

Each call produces a fresh, single-use e value. Use it immediately in the next step - it cannot be reused.

Verify the tap

Submit the chip_id and e value to verify the chip. This is the core API call: it validates authenticity, records the tap, and returns a session token.

// Returns a session scoped to this tap; session.item is the verified unit.
const session = await endstate.verify({
  chip_id: chip.chip_id,
  e: tap.e,
});

curl -X POST https://api2.endstate.io/v1/taps \
  -H "Authorization: Bearer end_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chip_id": "ABCDEF0123",
    "e": "C78566198547116F3A715DC1C62AF96F"
  }'

Response

{
  "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "session_token": {
    "token": "end_sess_AbCd1234EfGh5678IjKl9012MnOp",
    "expires_at": "2026-06-15T10:12:00.000Z",
    "scope": {
      "chip_id": "ABCDEF0123",
      "unit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "c0ffee00-1234-5678-90ab-cdef01234567"
    }
  },
  "chip": {
    "chip_id": "ABCDEF0123",
    "scan_count": 1
  },
  "unit": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": null,
    "name": null,
    "attributes": null,
    "collection": {
      "id": "8e1a7f50-90ab-4cde-b012-3456789abcde",
      "name": "Summer Tee 2026",
      "external_id": null,
      "contract": {
        "address": "0x1111111111111111111111111111111111111111",
        "chain_id": 84532,
        "status": "active"
      },
      "token": {
        "status": "active",
        "serial": 1
      }
    }
  },
  "redirect_url": null,
  "dry_run": false
}

Two fields to note:

object

Contains a short-lived token value (end_sess_...) that proves this chip was just tapped. Valid for 600 seconds by default. Pass the token string to a client to authorize unit-scoped actions without exposing your API key.

object

The digital record for the verified item, including its issuance status and serial number.

If verification fails (e.g., the e value was already used), the API returns a structured error. Branch on error.code - see Errors.POST /v1/taps is the only endpoint that issues session tokens, and it takes either credential: your API key when your server makes the call, or a publishable key (end_pk_live_...) when a page calls it directly with no backend of your own behind it. See Host your own verify page.

Introspect the session token (optional)

Your client can confirm the session token’s scope without holding an API key. Send the token string from the session_token object as the bearer credential.

// The session already knows its scope - this re-reads it from the API.
const current = await session.sessionTokens.current();

curl https://api2.endstate.io/v1/session-tokens/current \
  -H "Authorization: Bearer end_sess_AbCd1234EfGh5678IjKl9012MnOp"

Response

{
  "expires_at": "2026-06-15T10:12:00.000Z",
  "scope": {
    "chip_id": "ABCDEF0123",
    "unit_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_id": "c0ffee00-1234-5678-90ab-cdef01234567"
  }
}

This endpoint accepts only end_sess_* tokens - not API keys. Use it from browser or mobile clients to confirm a verified session without exposing server credentials.

Next steps

Core concepts

Understand collections, units, chips, and how they fit together.

Verify a unit

The full production verification guide, including real chip handling.

Claim a unit

Use the session token you just received to transfer the unit to a recipient.

Credentials

API keys, session tokens, and security best practices.

Get started

Settings

Core concepts

API conventions

Updates

Next steps

Core concepts

Verify a unit

Claim a unit

Credentials

​Next steps

Core concepts

Verify a unit

Claim a unit

Credentials

Next steps