API Reference

Chains

Create, retrieve, and verify proof chains. The chain is the core object in SwiftProof.

POST /v1/chains

Create a new chain. Returns confirmation URLs for each actor and a tracking URL for the end customer.

Request body

Parameter	Type	Description
title	string required	Human-readable name for this chain. Shown to actors and on the tracking page.
actors	array required	Ordered list of handoff objects. Minimum 1, maximum 10.
actors[].event	string required	Name of this step. e.g. `"packed"`, `"collected"`, `"delivered"`.
actors[].actor	string required	Display name of the person responsible for confirming this step.
metadata	object optional	Arbitrary key-value pairs attached to the chain. Returned in verification responses.
expires_in_hours	integer optional	Hours before confirmation links expire. Default 48. Min 1, max 168.

POST /v1/chains
{
  "title": "Order #4821 — Lekki Phase 1",
  "metadata": { "orderId": "4821" },
  "expires_in_hours": 48,
  "actors": [
    { "event": "packed",    "actor": "Kitchen — Surulere" },
    { "event": "collected", "actor": "Rider — Emeka"      },
    { "event": "delivered", "actor": "Rider — Emeka"      }
  ]
}

Response

Field	Type	Description
chain_id	string	Unique chain identifier. Store this to verify later.
status	string	`open` \| `completed` \| `failed`
tracking_url	string	Share with the end customer. No login required.
handoffs	array	One object per actor, each with a `confirmation_url` and `expires_at`.
created_at	string	ISO 8601 timestamp.

GET /v1/chains/:chain_id

Retrieve the current state of a chain, including which steps have been confirmed and which are pending.

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

GET /v1/chains/:chain_id/verify

Verify the integrity of a completed chain. Returns the full audit trail with tamper detection. See Verification for full details.

GET /v1/chains

List chains for your project. Returns the 20 most recent by default.

Query param	Type	Description
limit	integer	Number of results. Default 20, max 100.
status	string	Filter by status: `open`, `completed`, `failed`.
before	string	Cursor for pagination. Pass `chain_id` of last result.