Claims

A claim transfers on-chain ownership of a unit to a recipient wallet address. It is the action that hands a verified physical item to a new owner. Claims are authorized by a session token - the user must have just tapped that unit’s chip. This binds an ownership change to a real, recent tap of the physical product.

A claim hands a unit to its first owner, and Endstate can submit it for you. To move a unit between owners afterwards, use a transfer - the current owner submits that one from their own wallet.

For a step-by-step walkthrough from the tap to on-chain confirmation, follow the Claim a unit guide. This page is the reference.

How claiming works

Verify a tap

The user taps the item’s chip; your server verifies it (POST /v1/taps) and receives a session token scoped to that chip and unit.

Create the claim

Call POST /v1/units/{unit_id}/claims with the recipient’s wallet address and an execution mode, authorized by the session token. Endstate signs the transfer authorization for the unit’s token.

Settle on-chain

Depending on the execution mode, Endstate either submits the transfer transaction for you, or returns a transaction for you to broadcast.

Poll for status

Poll GET /v1/units/{unit_id}/claims/{claim_id} until status is claimed.

Execution modes

The execution field controls who broadcasts the on-chain transaction.

Mode	What Endstate does	What you do
`endstate_relay` (default)	Signs and submits the transfer transaction on your behalf.	Poll for status.
`client_broadcast`	Signs the transfer and returns a ready-to-send transaction in `submission`. Does not submit.	Broadcast `submission` to the network yourself, then poll for status.

With client_broadcast, the response includes submission: { to, data } - to is the collection’s contract address and data is the encoded transfer call. Send it as a transaction on the network the collection was provisioned on.

Authorization

POST /v1/units/{unit_id}/claims requires a session token (end_sess_...), and that token must come from a tap of the same unit’s chip. An API key alone cannot create a claim - claiming always traces back to a physical tap. GET /v1/units/{unit_id}/claims/{claim_id} accepts either an API key or a session token, so your backend or your client can poll for status. (Client-side polling from a browser requires your web origin on your organization’s CORS allowlist - see Session tokens.)

Create a claim

POST /v1/units/{unit_id}/claims

string

required

The recipient’s wallet address (EVM address, 0x followed by 40 hex characters). Ownership of the unit transfers to this address.

string

default:"endstate_relay"

endstate_relay - Endstate submits the transaction for you. client_broadcast - Endstate returns a transaction in submission for you to broadcast.

Endstate relay

await session.claims.create({
  to: "0x1111111111111111111111111111111111111111",
  execution: "endstate_relay",
});

curl -X POST https://api2.endstate.io/v1/units/22222222-2222-4222-8222-222222222222/claims \
  -H "Authorization: Bearer end_sess_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "0x1111111111111111111111111111111111111111",
    "execution": "endstate_relay"
  }'

Response

{
  "id": "00000000-0000-4000-8000-000000000000",
  "unit_id": "22222222-2222-4222-8222-222222222222",
  "to": "0x1111111111111111111111111111111111111111",
  "from": "0x2222222222222222222222222222222222222222",
  "status": "claiming",
  "created_at": "2026-06-15T12:00:00.000Z"
}

Client broadcast

Pass "execution": "client_broadcast". The response adds a submission object - broadcast it to the network yourself.

Response

{
  "id": "00000000-0000-4000-8000-000000000000",
  "unit_id": "22222222-2222-4222-8222-222222222222",
  "to": "0x1111111111111111111111111111111111111111",
  "from": "0x2222222222222222222222222222222222222222",
  "status": "claiming",
  "submission": {
    "to": "0x3333333333333333333333333333333333333333",
    "data": "0x..."
  },
  "created_at": "2026-06-15T12:00:00.000Z"
}

Broadcasting the transaction

The submission is already authorized by Endstate’s signature, so any account with gas on the collection’s network can broadcast it - your own funded account or relayer works, and the recipient never signs. You need an RPC endpoint for that network and a sender account with gas.

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const walletClient = createWalletClient({
  account: privateKeyToAccount(process.env.SENDER_KEY),
  transport: http(process.env.RPC_URL), // RPC for the collection's network
});

const hash = await walletClient.sendTransaction({
  to: claim.submission.to,
  data: claim.submission.data,
});

import { Wallet, JsonRpcProvider } from "ethers";

const wallet = new Wallet(
  process.env.SENDER_KEY,
  new JsonRpcProvider(process.env.RPC_URL),
);

const tx = await wallet.sendTransaction({
  to: claim.submission.to,
  data: claim.submission.data,
});

Use any EVM wallet client or signer - see the viem or ethers docs for wallet setup. After broadcasting, poll the claim for status.

Claim status

GET /v1/units/{unit_id}/claims/{claim_id} - poll this until the claim settles.

await endstate.claims.get(
  "22222222-2222-4222-8222-222222222222",
  "00000000-0000-4000-8000-000000000000",
);

curl https://api2.endstate.io/v1/units/22222222-2222-4222-8222-222222222222/claims/00000000-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer end_sess_..."

`status`	Meaning
`claiming`	The transfer is in progress (signed, submitted, or awaiting confirmation). Keep polling.
`claimed`	Ownership transferred and confirmed on-chain. Terminal.
`expired`	The signed authorization expired before it settled. Terminal - create a new claim.
`failed`	The transaction failed or was dropped. Terminal - create a new claim.

The signed transfer authorization is valid for 30 minutes from claim creation; a claim that does not settle in that window becomes expired. With endstate_relay this rarely matters - Endstate submits immediately. With client_broadcast, broadcast the submission well within the window.

The claim object

string (UUID)

The claim’s unique identifier.

string (UUID)

The unit being transferred.

string

The recipient wallet address.

string

The current owner’s wallet address.

string

One of claiming, claimed, expired, failed.

object | null

Present only for client_broadcast. The transaction to broadcast - to (the collection’s contract address) and data (the encoded transfer call). null or absent for endstate_relay.

string (ISO-8601)

When the claim was created.

Errors

Code	HTTP	When
`claim.in_progress`	409	A claim is already open for this unit. Wait for it to settle before starting another.
`claim.already_to_recipient`	409	The unit is already owned by, or being claimed to, that address.
`claim.owner_unknown`	409	The unit’s current owner cannot be determined yet.
`unit.not_minted`	409	The unit has not been issued yet - pair a chip and wait for `token.status: "active"` before claiming.
`claim.not_found`	404	No claim with that ID exists for the unit.
`session_token.wrong_chip`	403	The session token is bound to a different unit than the one in the path.
`session_token.invalid_or_expired`	401	The session token is unknown or has expired - re-verify a tap.

Branch on error.code, not the HTTP status. See Errors for the full envelope.

Next steps

Session tokens

How a tap produces the session token that authorizes a claim.

Units

The unit a claim transfers, and its issuance lifecycle.

Get started

Settings

Core concepts

API conventions

Updates

How claiming works

Execution modes

Authorization

Create a claim

Endstate relay

Client broadcast

Broadcasting the transaction

Claim status

The claim object

Errors

Next steps

Session tokens

Units

​How claiming works

​Execution modes

​Authorization

​Create a claim

​Endstate relay

​Client broadcast

​Broadcasting the transaction

​Claim status

​The claim object

​Errors

​Next steps

Session tokens

Units

How claiming works

Execution modes

Authorization

Create a claim

Endstate relay

Client broadcast

Broadcasting the transaction

Claim status

The claim object

Errors

Next steps