Reference
Protocol reference
Canonical details for request headers, webhook events, and error handling on Chest Gate.
Last updated April 22, 2026
This page documents wire-level details. Use it alongside the API provider and skill / MCP author guides. Those guides explain when to reach for each header. This page explains what each one does.
Request headers
Headers you may send or observe on paid requests. Combine as appropriate per the guides.
| Header | Direction | Purpose |
|---|---|---|
X-Chest-Referrer-Key: cg_pub_live_... | Request | API-key attribution path. One key per integration partner. |
X-Referrer-Wallet | Request | Referrer wallet address, paired with a signature header. |
X-Referrer-Sig | Request | Signature over the request canonicalization. Validates wallet ownership. |
X-Payment | Request | Base64-encoded x402 payment payload. |
X-Payment-Response | Response | Settlement receipt including on-chain transaction reference. |
Webhook events
Events are delivered to your registered webhook URL. Consumers must be idempotent by deliveryId, deliveries retry with exponential backoff and eventually dead-letter.
| Event | When it fires | Key payload fields |
|---|---|---|
call.attributed | Attribution resolved (seconds after request). | callId, slug, referrer |
call.settled | Settlement + split distribution finalized on-chain. | callId, distributeTx, split |
call.failed | Settlement or downstream distribution failed. | callId, reason, retryable |
Error classes
HTTP status codes you should expect to see and how to respond to each.
| Status | Meaning | Client action |
|---|---|---|
401 Unauthorized | Invalid or missing auth material. | Check API key scope, signature validity, or wallet ownership. |
402 Payment Required | Missing or invalid payment payload. | Retry with a valid X-Payment header. |
409 Conflict | Handle already taken, or resource state conflicts. | Pick a different handle; do not retry the same request. |
429 Too Many Requests | Rate limit exceeded for your caller tier. | Honor Retry-After and back off. |
Limits and retries
- Webhook deliveries retry with exponential backoff and eventually dead-letter.
- Proxy requests are rate-limited by caller tier: API key > signed headers > unsigned.
- Downstream consumers must be idempotent by
deliveryId.