Developer Docs

Appearance

Go-Live Checklist ​

Use this checklist before enabling your integration for real users. Each item maps to a specific failure mode that has been observed in pre-production integrations.

1. Authentication & Keys ​

  • [ ] Production API key is stored as an environment variable — never committed to source control or hardcoded.
  • [ ] API key is used server-side only — no production key is exposed in browser or mobile client code.
  • [ ] SDK API key is separate from the API key — they are different credentials with different scopes.
  • [ ] Only the intended production credential is present in production config — verify your deployment pipeline substitutes the correct key.
  • [ ] Key rotation procedure is documented — you know how to rotate the key and whom to contact if a key is compromised.

2. Customer Onboarding ​

  • [ ] KYC status is validated before registration — only customers with SumSub status GREEN or FINISHED are registered.
  • [ ] customerId uniqueness is enforced — your system generates deterministic, collision-free customer IDs.
  • [ ] Idempotency is handled — CUSTOMER_EXISTS and ADDRESS_EXISTS errors are treated as success on retry.
  • [ ] Multiple address support is implemented — if customers can connect additional wallets, the add-address endpoint is called.

3. Risk Assessment & Monitoring ​

  • [ ] RISK_ASSESSMENT webhook is configured and reachable — Holyheld can deliver webhook events to your endpoint.
  • [ ] Webhook signature verification is implemented — your endpoint validates the request source before processing events.
  • [ ] HIGH and VERY HIGH risk scores block settlement — your integration does not submit quotes for high-risk addresses.
  • [ ] Pre-flight risk check is in place — call Get Risk by Address before creating a settlement quote, not only after receiving the webhook.

4. Settlement ​

  • [ ] Quote expiry is handled — if the user takes more than 15 minutes, you request a new quote rather than submitting the expired one.
  • [ ] Settlement status is polled after execution — you poll GET /partner/settlement/status/{quoteId} every 15–30 seconds until a terminal state is reached.
  • [ ] SETTLEMENT_STATUS_CHANGE webhook is handled — your system processes webhook status updates and reconciles them with poll results.
  • [ ] FULFILLMENT_DENIED is handled — you surface an appropriate message to the user and do not retry automatically.
  • [ ] ERROR status is handled — you surface an error state and have a support path for affected users.
  • [ ] Retry logic uses exponential backoff — you do not retry 429 responses immediately. See Authentication for a reference implementation.
  • [ ] Settlement status is checked before retrying execute — you never submit the same quoteId twice without verifying it was not already accepted.

5. SDK Integration ​

  • [ ] Off-ramp is tested end-to-end with $SDKTEST — the onHashGenerate callback fires with a real transaction hash and the SDK call resolves successfully.
  • [ ] On-ramp is tested with a real Holyheld mobile app — requestOnRamp + watchRequestId complete successfully.
  • [ ] UnexpectedWalletNetwork is caught — users are prompted to switch chains if their wallet is on the wrong network.
  • [ ] UserRejectedTransaction and UserRejectedSignature are caught — users can retry without refreshing.
  • [ ] Token approval step is handled — the UI indicates progress during the approving step if the token requires an ERC-20 allowance.
  • [ ] getServerSettings() is checked on load — your UI respects both isTopupEnabled and isOnRampEnabled, and shows appropriate messaging if off-ramp or on-ramp is temporarily unavailable.

6. Compliance & Regions ​

  • [ ] Supported regions are enforced — customers in countries where off-ramp/on-ramp is unavailable cannot initiate those flows.
  • [ ] Restricted countries are blocked — customers in sanctioned countries are rejected before KYC registration.
  • [ ] KYC flow is in place — you have integrated SumSub or another approved KYC provider and the verification result reaches Holyheld before registration.

7. Observability ​

  • [ ] Webhook delivery failures are alerted — you monitor for missed or failed webhook deliveries and have a reconciliation process.
  • [ ] Settlement errors are logged with quoteId — you can look up any settlement by its quoteId for support investigations.
  • [ ] SDK errors are logged with error codes — HolyheldSDKErrorCode values are captured and surfaced to your monitoring system.
  • [ ] Rate limit responses are monitored — a spike in 429 responses indicates a traffic problem that should be investigated.

8. Agentic Access (if using Payments for AI Agents) ​

Skip this section if you are not using the Payments for AI Agents API.

  • [ ] Bearer token is stored as an environment variable — not hardcoded in source files or committed to version control.
  • [ ] Bearer token is kept local — if using an MCP server, it runs on the user's own machine and the token never leaves the local environment.
  • [ ] Card data is treated as sensitive — if using GET /card-data, your agent fetches it only for active checkout flows and never logs full PAN/CVV values.
  • [ ] Spending limit is configured in the Holyheld dashboard — each agent token has a maximum cumulative top-up limit set under Settings → Agentic access.
  • [ ] AI_TOPUP_LIMIT_EXCEEDED is handled — your agent surfaces the error to the user immediately, stops retrying, and pauses autonomous top-ups until the user resets the limit in the dashboard.
  • [ ] AI_TOPUP_INSUFFICIENT_BALANCE is handled — your agent notifies the user that they need to add crypto funds to their Holyheld account. It does not retry.
  • [ ] Post-top-up polling is implemented — after a successful POST /topup-request, your agent polls GET /balance every 30 seconds for up to 5 minutes and reports success only when the balance has increased.
  • [ ] Pre-top-up balance is recorded — your agent captures the balance before requesting a top-up so it can reliably detect when the balance has updated.
  • [ ] Top-up is not retried blindly — if a network error occurs during POST /topup-request, the agent checks the balance before deciding to retry (to avoid double top-ups).
  • [ ] Amount is formatted as a string — top-up amounts are sent as strings matching ^\d+(\.\d{1,2})?$ (e.g. "50.00"), not as numbers.

9. Final Steps ​

  • [ ] End-to-end test in production with a real user and a small amount — verify the complete flow from registration through settlement with real funds before launching at scale.
  • [ ] Support contact is established — you have a direct line to your Holyheld point of contact for production issues.
  • [ ] Key compromise procedure is tested — your team knows how to rotate a key without downtime.