API Reference

Handoffs

Individual steps within a chain. Each handoff has one actor and one confirmation link.

GET /v1/chains/:chain_id/handoffs

List all handoffs for a chain with their current status.

JavaScript
const handoffs = await sp.chains.handoffs('sp_ch_a96fec076ffd44f4');

Handoff object

Field	Type	Description
handoff_id	string	Unique identifier for this handoff step.
event	string	Name of the event as defined at chain creation.
actor	string	Display name of the responsible actor.
status	string	`pending` \| `confirmed` \| `expired`
confirmation_url	string	One-time URL. Null once the handoff is confirmed or expired.
confirmed_at	string	ISO 8601 timestamp. Null until confirmed.
expires_at	string	ISO 8601 timestamp when the link expires.
location	string	Reverse-geocoded address from the actor's GPS at confirmation time.
coordinates	object	`lat` and `lng` captured at confirmation.

POST /v1/chains/:chain_id/handoffs/:handoff_id/resend

Generate a fresh confirmation link for a pending or expired handoff. Useful when an actor loses the original link or it expires before they could confirm.

The previous link is immediately invalidated when you resend. Only the new link will work. The resend event is logged in the audit trail.

JavaScript
const result = await sp.handoffs.resend(
  'sp_ch_a96fec076ffd44f4',
  'sp_hf_001'
);

console.log(result.confirmation_url); // New link

Handoff lifecycle

Every handoff moves through a simple state machine.

pending — created, link active, waiting for actor confirmation.
confirmed — actor tapped confirm. GPS, timestamp, and signature captured. Terminal state.
expired — link passed its expires_at without confirmation. Use resend to issue a new link and move back to pending.

Only the current active handoff in the sequence can be confirmed. An actor cannot confirm step 3 before steps 1 and 2 are done.