Quickstart - Endstate API

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 uses curl.

Every /v1/* request includes your API key in the Authorization header — Authorization: Bearer end_sk_test_.... Keep it server-side only, and never expose it in browser code. See Authentication 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.

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

{
  "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 GET /v1/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.

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

{
  "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.

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

{
  "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.

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

{
  "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, the /tap endpoint generates one for you.

curl -X POST https://api2.endstate.io/v1/chips/ABCDEF0123/tap \
  -H "Authorization: Bearer end_sk_test_..."

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

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

Verify the tap

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

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

{
  "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:

session_token — an object containing 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.
unit — 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.

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.

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

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

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.

Authentication

API keys, session tokens, and security best practices.

​Next steps

Core concepts

Verify a unit

Claim a unit

Authentication

Next steps