Developer Docs

Appearance

Changelog ​

Release notes for all BRRR products: API APIs, SDK Holyheld SDK, and Agentic Payments for AI Agents API.

April 2026 ​

SDK v4.1.5 ​

Bug Fixes ​

  • Fixed SDK build and export compatibility issues

SDK v4.1.4 ​

Features ​

  • Added new network: hyperEVM

March 2026 ​

API APIs ​

Added ​

  • Settlement status enum now includes all 7 documented states: CREATED, CONFIRMED, EXPIRED, PROCESSING, SENT, FINISHED, ERROR
  • RISK_ASSESSMENT webhook payload now includes reviewData object for TOPUP events, containing fromAddress, amount, and totalAmount fields
  • SETTLEMENT_STATUS_CHANGE webhook now fires for all status transitions including terminal states (FINISHED, EXPIRED, ERROR)

Documentation ​

  • Settlement execution overview updated with full state machine diagram and timing guide
  • Webhook delivery and retry schedule documented (4 retries over ~26 hours)
  • Idempotency behaviour documented for all endpoints
  • Multi-language code samples (curl, JavaScript, Python) added across the API Reference

SDK v4.1.3 ​

Features ​

  • Updated EVM return values for offRamp.topup and offRamp.topupSelf: both methods now return the transaction hash

Agentic v0.0.1 — Initial Release ​

Added ​

  • Initial release of the Payments for AI Agents API (v0.0.1) — a purpose-built HTTP API for AI agents acting on behalf of a single Holyheld user account.
  • GET /balance endpoint — returns the current EUR card balance as a decimal string.
  • GET /card-data endpoint — returns card number, expiration date, cardholder name, CVV, and billing address for checkout flows.
  • POST /topup-request endpoint — initiates an asynchronous top-up by transferring funds from the Holyheld main account to the Holyheld card.
  • Bearer token authentication (Authorization: Bearer <token>) issued from the Holyheld dashboard under Settings → Agentic access.
  • Configurable per-token cumulative spending limit — enforced server-side; returns AI_TOPUP_LIMIT_EXCEEDED when exceeded.

Error codes introduced ​

CodeHTTPDescription
AI_AUTHORIZATION_INVALID401 / 403Missing, invalid, or revoked bearer token
AI_TOPUP_INSUFFICIENT_BALANCE500Not enough available balance on the user's Holyheld main account
AI_TOPUP_LIMIT_EXCEEDED500Agent cumulative spending limit reached
WRONG_REQUEST400Malformed request body (e.g. invalid amount format)
INTERNAL_SERVER_ERROR500Transient server-side error; retry with exponential backoff

Documentation ​

  • Introduction — API overview, use cases, architecture diagram, and comparison with the APIs.
  • Authentication — Bearer token setup, security best practices, and spending limit configuration.
  • Get Balance — GET /balance endpoint reference with multi-language examples.
  • Get Card Data — GET /card-data endpoint reference and guidance for handling sensitive card details.
  • Top Up Card — POST /topup-request reference, amount format rules, polling pattern, and full error decision tree.
  • Error Reference — Recovery guidance for every error code, with TypeScript implementation using UserActionRequiredError.
  • Build an MCP Server — Step-by-step guide to wrapping the API as Claude tools using @modelcontextprotocol/sdk.
  • Agent Patterns — Best practices: balance-aware spending, threshold-based auto top-up, safe polling, limit escalation, and anti-patterns.

November 2025 ​

API APIs ​

Added ​

  • quoteType field added to QuoteBeneficiary request body: fiat_to_token or token_to_fiat
  • Settlement quote response now includes per-beneficiary amountGBPReference for GBP cross-reference reporting

Changed ​

  • confirmDeadline window extended from 10 minutes to 15 minutes for settlement quotes

SDK v4.1.2 ​

Features ​

  • Added new network: plasma

October 2025 ​

SDK v4.1.1 ​

Features ​

  • Updated dependencies: viem and internal tools

September 2025 ​

SDK v4.1.0 ​

Features ​

  • Added topupSelf method for off-ramping to the connected user address without tag argument

June 2025 ​

API APIs ​

Added ​

  • GET /api/v1/rates/{currency}/{network}/{token} endpoint introduced for real-time exchange rate lookups
  • externalTransactionId field added to QuoteBeneficiary to support partner-side reconciliation

Fixed ​

  • GET /api/v1/customer/risk/{customerId} now returns all registered addresses for a customer, including those with no activity yet (previously returned an empty array until the first TOPUP event)

SDK v4.0.5 ​

Bug Fixes ​

  • Fixed return values in internal methods

May 2025 ​

SDK v4.0.4 ​

Bug Fixes ​

  • Fixed return values in internal methods

SDK v4.0.3 ​

Bug Fixes ​

  • Fixed return values in internal methods

SDK v4.0.2 ​

Bug Fixes ​

  • Renamed method evm.offRamp.getAvailableEVMNetworks to evm.offRamp.getAvailableNetworks

SDK v4.0.1 ​

Features ​

  • Added support for the Solana network (currently available for off-ramp only)

BREAKING CHANGES ​

  • SDK structure has changed: network-specific functionality is now accessed via sdk.evm and sdk.solana namespaces (e.g. sdk.evm.offRamp, sdk.solana.offRamp). Each level in the hierarchy (e.g. sdk, sdk.evm) may expose shared methods relevant to all submodules
  • One method was renamed: offRamp.getTagInfoForTopUp → getTagInfo
  • Some methods now accept a single configuration object instead of multiple positional arguments: offRamp.convertTokenToEUR, offRamp.convertEURToToken, offRamp.getTopUpEstimation, offRamp.topup, onRamp.convertTokenToEUR, onRamp.convertEURToToken, onRamp.getOnRampEstimation, onRamp.requestOnRamp
  • The return structure of the method evm.getWalletBalances has changed
  • Some TypeScript types were renamed for consistency with the new SDK structure: RequestOnRampResult → RequestOnRampEVMResult, WalletBalances → WalletBalancesEVM, WalletToken → WalletTokenEVM, ConvertTopUpData → ConvertTopUpDataEVM, TransferData → TransferDataEVM, NetworkInfo → NetworkInfoEVM
  • The SDK now requires a Node.js Buffer polyfill

See the updated SDK documentation for details

March 2025 ​

API APIs — Initial Release ​

Added ​

  • Initial public release of the APIs
  • Customer registration: POST /api/v1/customer/register, POST /api/v1/customer/register/address
  • Risk assessment: GET /api/v1/customer/risk/{customerId}, GET /api/v1/customer/risk/address/{addressEVM}
  • Settlement estimation: POST /api/v1/settlement/quote
  • Settlement execution: POST /api/v1/settlement/execute, GET /api/v1/settlement/status/{quoteId}
  • Offboarding: POST /api/v1/customer/remove, POST /api/v1/customer/remove/address
  • Webhooks: RISK_ASSESSMENT, SETTLEMENT_STATUS_CHANGE

SDK v3.2.5 ​

Features ​

  • Corrected HTTP headers in requests

SDK v3.2.4 ​

Features ​

  • Updated dependencies: viem and internal tools

SDK v3.2.3 ​

Features ​

  • Added networks (sonic, hyperliquid, berachain, plume)
  • Updated viem to ^2.22.23

January 2025 ​

SDK v3.2.2 ​

Features ​

  • Updated dependencies: viem and internal tools

December 2024 ​

SDK v3.2.1 ​

Bug Fixes ​

  • Fixed the method onRamp.watchRequestId

SDK v3.2.0 ​

Features ​

  • Added method onRamp.getOnRampEstimation

BREAKING CHANGES ​

  • Changed the arguments and the return value of the method onRamp.watchRequestId. See Withdraw
  • Changed the arguments of the method offRamp.getTopUpEstimation. See Deposit
  • The offRamp.getTopUpEstimation method now supports estimation only for native tokens used for gas fees.

November 2024 ​

SDK v3.1.0 ​

Features ​

  • Fixed conversion methods onRamp.convertTokenToEUR and onRamp.convertEURToToken
  • Added properties minOnRampAmountInEUR and maxOnRampAmountInEUR in the method getServerSettings

BREAKING CHANGES ​

  • Method onRamp.requestOnRamp no longer requires WalletClient to be passed. Changed the order and number of arguments. See Withdraw
  • Changed the arguments in the methods onRamp.convertTokenToEUR and onRamp.convertEURToToken. See Withdraw

SDK v3.0.1 ​

Bug Fixes ​

  • Fixed the method onRamp.getAvailableNetworks

SDK v3.0.0 ​

Features ​

  • Added on-ramp flow

BREAKING CHANGES ​

  • The methods getTagInfoForTopUp, convertTokenToEUR, convertEURToToken, and topup are now invoked via the offRamp object for the off-ramp flow. For example: holyheldSDK.offRamp.getTagInfoForTopUp('SDKTEST')

September 2024 ​

SDK v2.1.2 ​

Features ​

  • Changed the maximum limit for the test tag (1 EUR)

August 2024 ​

SDK v2.1.1 ​

Features ​

  • Added networks (bsc, manta, alephzero)

SDK v2.1.0 ​

Features ​

  • Added method validateAddress

March 2024 ​

SDK v2.0.0 ​

Features ​

  • Added methods getAvailableNetworks and getTopUpEstimation
  • Updated viem to ^2.7.8

BREAKING CHANGES ​

  • Added init asynchronous method that must be called after instantiating an SDK object
  • Changed the way to call utility methods getNetwork, getNetworkByChainId, getNetworkChainId: after SDK initialization they are available as SDK object methods
  • Changed the return value in utility methods getNetwork and getNetworkByChainId, see NetworkInfo type in README

February 2024 ​

SDK v1.2.4 ​

Bug Fixes ​

  • Fixed maximum amount calculation

December 2023 ​

SDK v1.2.3 ​

Bug Fixes ​

  • Fixed getting an avatar in the method getTagInfoForTopUp

November 2023 ​

SDK v1.2.2 ​

Bug Fixes ​

  • Fixed error handling in methods: getServerSettings, getTagInfoForTopUp, convertTokenToEUR, convertEURToToken

SDK v1.2.1 ​

Bug Fixes ​

  • Updated files field in package.json

SDK v1.2.0 ​

Features ​

  • Updated USDC to Circle USDC for Polygon and Optimism