See /concepts/lifecycle for the end-to-end flow (policy → trigger → bond → wait/sell decision).
policyId — happens server-side.
Sequence
Full TypeScript example
curl equivalent
Field deep-dive
productName— canonical name (FLASHBTC1H-001,FLASHETH24-001, …). Preferred input — the API resolves both theproductIdhash AND the per-shieldassetliteral from it. See Products and assets for the registered set.productId— bytes32 hash. Optional alternative toproductName. Compute askeccak256(toUtf8Bytes('FLASHBTC24-001')). Pre-computed values are listed in Shields.coverageAmount— string of USDC base units. **Minimum:"100000000"(= 100 ="100000000", $1,000 ="1000000000". Always pass as a string to preserve precision.asset— bytes32 of the asset symbol. Optional — the API auto-resolves the per-shield literal when omitted. This must equal the product’scoveredAsset(exposed onGET /products) — not the USDC payment token. Each shield expects a specific value (BTCfor FlashBTC,ETHfor FlashETH); sending the wrong one reverts withInvalidAsset(bytes32)(selector0x8196d462). See Covered asset vs payment asset for the distinction.buyer— the wallet that pays the USDC premium (NOT the relayer). Must hold ≥ premium and have approved the relayer-side spender.
Idempotency
PassIdempotency-Key: <uuidv4> on every retryable purchase. Replays return
the original response without double-spending. The key is scoped per agent;
it’s safe (and good practice) to derive a fresh UUID per logical attempt.
Errors
| HTTP | Code | Retry? |
|---|---|---|
| 400 | validation_error | No |
| 401 | invalid_api_key | No |
| 422 | shield_paused | Maybe later |
| 422 | exceeds_capacity | Maybe later |
| 429 | rate_limit | Yes (backoff) |
| 5xx | server_error | Yes (≤3 attempts) |