Claims - Endstate API

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/chips/ {chip_id}) 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.

execution

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

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"
  }'

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

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

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.

unit_id

string (UUID)

The unit being transferred.

string

The recipient wallet address.

from

string

The current owner’s wallet address.

status

string

One of claiming, claimed, expired, failed.

submission

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.

created_at

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.

​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