Endpoints

All routes are served via AWS HTTP API Gateway. Responses are JSON. See Authentication for the storage, relayer, and admin schemes.

Managed storage

POST /storage/sign

Return one short-lived signed object operation. Requires a valid Privy access token in the Authorization: Bearer <token> header.

{
  "projectId": "0x… (bytes16)",
  "key": "0x… (SHA-256 content hash)",
  "operation": "put | get | head | delete"
}

The API derives the object path from the authenticated user ID, project ID, and content hash; callers cannot provide a bucket or object path.

{
  "url": "https://…",
  "method": "PUT",
  "headers": { "Content-Type": "application/octet-stream" },
  "expiresAt": "2026-…"
}

Errors: 400 (strict validation), 401 (missing, expired, or revoked session), 500.

Requests

POST /requests

Submit a new request. No authentication: the request is self-authenticating via the embedded EIP-712 signature.

{
  "chainName": "demo",
  "action": "WRITE_DATA_FOR",
  "params": { /* depends on action - see below */ }
}

{
  "requestId": "uuid",
  "chainName": "demo",
  "action": "WRITE_DATA_FOR",
  "signer": "0x...",
  "status": "pending",
  "params": { },
  "createdAt": "2026-...",
  "updatedAt": "2026-..."
}

Errors: 400 (validation), 500.

GET /requests

List requests with filtering and cursor pagination.

Query parameters (at least one filter required):

{
  "items": [ { "requestId": "...", "status": "pending", "...": "..." } ],
  "count": 10,
  "lastKey": "base64url-or-null"
}

To page, pass the returned lastKey on the next call. A null lastKey means the last page. Errors: 400, 401 (status/chainName query without relayer auth), 500.

GET /requests/{requestId}

Fetch a single request by its UUID. Public. Returns the full request object. Errors: 400, 404, 500.

PATCH /requests/{requestId}

Update a request's status. Requires relayer authentication. Used to claim a pending request (processing) or finalize it (success / failed).

{
  "status": "success",
  "txHash": "0x… (required when status=success)",
  "errorMessage": "string (required when status=failed, max 1000 chars)"
}

The pending → processing claim is atomic; a 409 Conflict means the request was already claimed or the state transition is invalid. Errors: 400, 401, 409, 500.

Admin: relayer whitelist

All admin routes require the X-Admin-Key header (see Authentication).

POST /admin/relayers

Add a relayer to the whitelist. Body: { "address": "0x...", "label": "optional" }. Response 201 with the created record. Errors: 400, 401, 500.

DELETE /admin/relayers/{address}

Remove a relayer. Response 200 { "message": "Relayer removed", "address": "0x..." }. Errors: 400, 401, 500.

GET /admin/relayers

List whitelisted relayers. Response 200 { "relayers": [...], "count": N }. Errors: 401, 500.

Actions and parameters

The params object of POST /requests is validated (via Zod) per action. Every action shares the meta-transaction fields relayerFee, timestamp, signer, v, r, s.

permit is the EIP-2612 signature object { deadline, v, r, s } that authorizes the DPC pull for a funded prism (fundAmount > 0). The relayer passes it to the Forwarder's createPrismFor, so funding and creation happen in one transaction with no prior approve. It is omitted when fundAmount is 0.

Error format

{ "error": "Human-readable message", "details": [ /* optional, for validation errors */ ] }