Tap sessions

A tap proves someone is holding a specific physical item. verify() records that tap and hands back a session scoped to it: every call the session makes carries the session credential, so the session token never has to be threaded through your own code.

Verify a tap

verify() takes the chipId and e from the tap and returns the session:

import { EndstatePublicClient, publishableKey } from "@endstate-sdk/core";

const endstate = new EndstatePublicClient({
  publishableKey: publishableKey(process.env.NEXT_PUBLIC_ENDSTATE_KEY),
});

const session = await endstate.verify({ chipId, e, c });

session.item; // the verified unit - no extra request
session.scope; // what this session authorizes
session.expiresAt; // when it stops working

It never takes a URL. To get a tap out of one, parse it first with tryParseTapUrl, which returns null rather than throwing:

import { tryParseTapUrl } from "@endstate-sdk/core";

const tap = tryParseTapUrl(window.location.href);
if (!tap) return renderTapPrompt();

const session = await endstate.verify(tap);

That handles both shapes a tap arrives in: an Endstate tap URL (/verify/{chip_id}?e= or /u/{chip_id}?e=), and a tap redirect destination on your own domain, where the values arrive as endstate_chip_id and endstate_e query parameters instead.

Keeping the parse separate is deliberate. “Is there a tap on this page?” is an offline question whose answer is often no - a direct visit, or a reload after the query was stripped - so it belongs in a branch rather than a try around a network call. See Host your own verify page for the full flow.

The e value is single-use. Never cache one and never replay one yourself. verify() derives its idempotency key from the tap, so a page refresh replays the original response instead of spending the credential and reporting a false “already scanned”.

Act on the session

Reading the unit is the start; the tap’s real payoff is acting on it. A verified session authorizes claiming the item for a customer and transferring it between owners. The unit comes from the session that the tap opened, so you supply only the recipient’s wallet address, and the session token authorizes the write.

const claim = await session.claims.create({ to: recipientAddress });

claim.status; // "claiming" first
const settled = await session.claims.waitUntilSettled(claim.id);
settled.status; // "claimed" | "expired" | "failed"

See Claim ownership and Transfer ownership for the worked browser walkthrough, including claim’s two execution modes. session.claims.create and session.transfers.create are the reference for the request body and error codes. The session exposes exactly what a tap authorizes:

Resource	Methods
`session.claims`	`create` · `get` · `waitUntilSettled`
`session.transfers`	`create` · `get` · `waitUntilSettled`
`session.sessionTokens`	`current` · `revoke`

Sessions cannot be refreshed

A new session needs a new tap. There is no refresh, by design - the session’s authority comes from someone having physically held the item.

session.isExpired(); // local clock check
session.msUntilExpiry(); // milliseconds remaining, or null
await session.revoke(); // end it early

isExpired() is a local clock check, for interface copy only. The SDK never gates a request on it: a device clock is not authoritative. The definitive answer is a 401 session_token.invalid_or_expired from the API.

Adopting a session you already hold

If your server issued the session, or you kept the token across a page reload, adopt it rather than re-verifying:

const session = endstate.session(token);

// Fill in expiry and scope, which a bare token does not carry.
await session.refreshScope();

Where the tap comes from

In a browser, core can capture the tap for you through a registered tap source, or take the output of @endstate-sdk/reader directly - see Browser. On a server, you already have chipId and e from whatever forwarded them to you.

Get started

Core SDK

Web SDK

Reader SDK

Verify a tap

Act on the session

Sessions cannot be refreshed

Adopting a session you already hold

Where the tap comes from

​Verify a tap

​Act on the session

​Sessions cannot be refreshed

​Adopting a session you already hold

​Where the tap comes from

Verify a tap

Act on the session

Sessions cannot be refreshed

Adopting a session you already hold

Where the tap comes from