# Curve x BRRR – Building an Onchain FX Marketplace

In the world of DeFi, [Curve Finance](https://curve.finance/){rel="nofollow"} has become synonymous with efficient onchain stablecoin trading. As a specialized automated market maker, Curve focuses on assets that typically trade at similar values, such as stablecoins, and employs a formula that minimizes slippage while keeping fees low. Liquidity providers earn yield from swap fees, and the platform's governance token, CRV, rewards participants for supporting the protocol.

## What makes Curve stand out?

- Ultra‑low slippage: Curve's modified AMM design ensures that stablecoins can be swapped with minimal price impact. This quality is critical when executing large trades or performing real‑time foreign exchange between pegged assets.
- Capital efficiency: By concentrating on like‑valued assets, Curve can maintain deep liquidity with relatively small pools. This makes swaps cheaper, increases capital efficiency, and reduces price volatility.
- Community governance: CRV token holders vote on fee parameters, pool additions, and reward distributions. Aligning with community interests helps sustain a resilient ecosystem.

## The BRRR Connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. When combined with Curve, BRRR transforms stablecoin trading into a global onchain FX marketplace.

## How Curve enriches BRRR

1. Onchain FX: A user wanting to convert crvUSD on Ethereum to EURC on another network can initiate a BRRR clearing request. BRRR broadcasts an RFQ to find the best swap, executes it on Curve, then bridges the resulting stablecoin to the destination chain—the result: a seamless FX trade without leaving the onchain DeFi ecosystem.
2. Intent-based settlement: BRRR's programmable intents enable multiple steps (swap, bridge, and lend) within a single atomic transaction. A fintech could wrap a Curve swap into a lending operation on [LLAMALEND](https://www.curve.finance/lend/ethereum/markets/){rel="nofollow"} using BRRR and payout through Visa's card network, all in the same settlement flow.

## Real-world applications

### Borderless payments and stablecoin FX

Businesses have enough to worry about without adding payments to the list. Hold crvUSD on Mainnet, but need to pay a supplier in EURC on Arbitrum? No Problem! Instead of struggling to complete complicated swap transactions, businesses can use the tokens they hold on hand, effectively BRRR. BRRR will convert crvUSD on Ethereum to EURC on Arbitrum via Curve's efficient pools, bridge the funds, and settle the payment with minimal fees- no banks or currency desks required.

### Effortless treasury management

BRRR monitors the markets so you don't have to. Multichain DAOs and fintech treasuries utilize BRRR to rebalance between different stablecoins automatically. Set your strategy and let BRRR trigger the Curve swap, route the funds to a yield vault, and record the entire transaction across chains for transparent auditing.

### Institutional Level Liquidity

BRRR enables financial institutions to supply stablecoin liquidity on Curve. These provisions earn yield from trading fees and CRV governance rewards, while BRRR ensures settlements are executed securely across networks.

## Who can benefit from BRRR

- Fintechs and institutions can offer new products — such as cross‑border payroll, remittances, or treasury rebalancing — powered by the synergy between Curve's liquidity pools and BRRR's settlement engine.
- DeFi developers can build next‑generation applications that bundle swaps, lending, and payments into simple user experiences, all secured by BRRR's atomic settlement flows.
- BRRR stakers gain exposure to a rapidly expanding onchain FX market. The integration of Curve into BRRR's settlement layer allows holders of BRRR tokens to benefit from trading volume and fees generated by crosschain FX operations.

Curve's low‑slippage stablecoin pools combined with BRRR's crosschain settlement layer create a robust onchain FX market. From institutions managing treasuries, liquidity provision, or yield generation to businesses managing global stablecoin payments, BRRR × Curve eliminates hassle and delivers the infrastructure to build, innovate, and grow.

Ready to join the onchain FX revolution? Reach out to the BRRR team and discover how your business or project can integrate Curve liquidity through BRRR's programmable settlement layer.


# AAVE x BRRR – Lend and Spend Markets for Real‑World DeFi

In the DeFi landscape, [Aave](https://aave.com/){rel="nofollow"} has become the go-to protocol for decentralized lending and borrowing, enabling users to earn yield on deposits and borrow assets using overcollateralized positions. Aave powers a multichain, trustless liquidity layer. When integrated with BRRR, a decentralized settlement and reconciliation layer, Aave evolves beyond lending into a programmable, real-world payments system. The result is DeFi-native capital that can be lent, borrowed, and spent instantly via traditional rails, such as card networks and SEPA transfers.

## What makes AAVE stand out:

- Non-custodial lending and borrowing: Users supply assets to earn interest or borrow against collateral through onchain smart contracts.
- Interest-bearing tokens: Deposits generate aTokens that accrue interest in real-time and can be used across the DeFi ecosystem.
- Multichain access: Aave operates across Ethereum, Polygon, Avalanche, and more—providing liquidity wherever needed.
- GHO: Aave's over‑collateralised, USD‑pegged stablecoin that you can mint directly against your deposits, with all interest flowing back to the DAO.
- Risk controls: Including isolated markets, stable/variable rates, and effective governance, minimize risk and support a diverse range of assets.

## The BRRR connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. When combined with Aave, BRRR unlocks "lend-and-spend" flows: borrow from Aave, convert via BRRR, and pay a merchant, all within one atomic operation.

## How AAVE enriches BRRR

1. Crypto-powered payments: A user borrows GHO, USDC, or EURC on Aave using ETH collateral. BRRR executes the borrow and settles the payment via card or SEPA from stablecoins, seamlessly linking onchain capital to fiat spending.
2. Programmable finance and payment flows: BRRR enables multi-step transactions. For example, a developer builds a wallet where users lend assets on Aave and spend the earned yield via a debit card. BRRR orchestrates the whole flow, including swaps, bridges, and offchain settlement.
3. Treasury automation: DAOs and fintechs use Aave to deploy idle capital for yield. BRRR enables real-time reconciliation and payments from Aave deposits, transforming a DeFi strategy into operational cash flow.

## Real-world applications - relevant to AAVE

### Lend, Borrow, and Spend

DeFi users deposit DAI into Aave, borrow GHO or USDC, and spend directly via BRRR-powered debit cards. No manual offramping, no exchanges - just lending and spending in one seamless flow.

### Cross-chain settlement

Fintechs can borrow Stablecoin X on Ethereum via Aave, but need to pay a supplier on Arbitrum in Stablecoin Y. BRRR handles the borrowing, bridging, swapping, and payment atomically across chains.

### Self-repaying loans

Users borrow stablecoins from Aave against yield-bearing collateral (e.g., stETH). BRRR routes yield to cover interest, allowing for real-world payments without depleting the principal, similar to a self-repaying credit card balance.

## Who can benefit from BRRR

- Fintechs and institutions can offer new products, including crypto-backed credit lines, yield-bearing savings accounts, and real-time global payments or treasury rebalancing, powered by the synergy between the Aave protocol and BRRR's settlement engine.
- DeFi developers can build next‑generation applications that bundle swaps, lending, and payments into simple user experiences, all secured by BRRR's atomic settlement flows.
- BRRR stakers gain exposure to a rapidly expanding onchain yield. The integration of Aave into BRRR's settlement layer allows holders of BRRR tokens to benefit from settling or reconciling positions in fiat with full compliance and transparency.

Aave's decentralized liquidity markets, combined with BRRR's crosschain programmable settlement, enable a new era of "lend-and-spend" finance. Whether for individuals, DAOs, or fintechs, this synergy brings DeFi closer to real-world usability, secure, seamless, and globally scalable.


# Arbitrum x BRRR – Real-Time Onchain Settlement

[Arbitrum](https://arbitrum.io/){rel="nofollow"} is a high-performance Layer 2 network built on Ethereum, designed to scale smart contract execution with faster block times and low fees. It enables secure, low-latency applications by using optimistic rollup technology while remaining fully EVM-compatible. With finality often achieved in under 2 seconds and very low gas costs, Arbitrum is ideal for real-time DeFi workflows, especially where speed and cost efficiency are crucial. When integrated with BRRR, Arbitrum becomes the ultimate real-time onchain settlement chain. BRRR provides the programmable clearing and reconciliation layer, while Arbitrum handles instant settlement of stablecoins and intent-based transactions.

## What makes Arbitrum stand out:

- Fast block confirmations: Finality is sub 2 seconds via a centralized sequencer, ideal for consumer-facing apps that require responsiveness.
- Low fees: Transactions cost a fraction of a cent, enabling microtransactions, cross-border remittances, and stablecoin payments at scale.
- Ethereum security: Transactions are eventually settled to Ethereum, combining fast L2 execution with L1-grade trust.
- Developer-ready tooling: Fully EVM-compatible with broad support for Solidity, standard wallets, and dApps.
- Early fintech adoption: Used by PayPal with PYUSD and Circle offering native USDC, and other major stablecoin providers for real-world payment infrastructure.

## The BRRR connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. Arbitrum was one of the earliest networks integrated into BRRR due to its low latency, reliability, and rich stablecoin ecosystem. BRRR’s design abstracts the complexity of multi-network settlements: it can initiate a payment on Arbitrum and reconcile it with offchain systems like banks and card processors, behind the scenes.

## How Arbitrum enriches BRRR

1. Instant stablecoin settlement: Arbitrum confirms transactions in sub 2 seconds. BRRR leverages this speed to instantly settle payments, making real-time crypto-to-fiat conversions usable for everyday payments.
2. High-volume payment handling: Fintech platforms can route thousands of transactions per minute through BRRR on Arbitrum without congestion or fee spikes, even during peak usage periods.
3. Cross-chain orchestration: With Arbitrum’s low-fee bridge ecosystem and BRRR’s multi-chain logic, developers can settle user intents originating on Ethereum or other L2s, but finalize them on Arbitrum for optimal cost and speed.
4. Trusted by stablecoin issuers: With native USDC, PYUSD, and other major stablecoins deployed on Arbitrum, BRRR can tap deep liquidity for seamless fiat to crypto conversion and off-ramp flows.

## Real-World applications

### Real-time spending from crypto wallets

A fintech user funds their Holyheld card via Arbitrum. BRRR handles the onchain stablecoin transaction, converts it via a router, and settles fiat to the merchant instantly with transparent gas costs.

### Treasury disbursements and payroll

Institutions hold USDC or PYUSD on Arbitrum. BRRR automates recurring payouts like salaries or supplier payments, using intent-based instructions, executed and reconciled on Arbitrum’s fast, final settlement layer.

### Stablecoin settlement for fintechs through APIs

A payment gateway integrates Arbitrum and BRRR to allow global customers to pay in stablecoins. The gateway receives fiat via BRRR’s conversion layer, while funds are settled trustlessly on Arbitrum in seconds.

## Who can benefit from BRRR

- Fintechs use Arbitrum and BRRR to access fast, reliable crypto rails for spending, disbursements, and stablecoin settlements.
- Protocols on Arbitrum benefit from BRRR as an offchain bridge to traditional payments, enhancing the utility of DeFi-native assets.
- Institutions leverage BRRR and Arbitrum to settle real-world obligations in a compliant, cost-efficient, and programmable way, unlocking instant, onchain-to-fiat flows.

Arbitrum’s low-latency infrastructure and BRRR’s settlement protocol form a seamless stack for real-time global payments. Whether powering microtransactions, corporate payouts, or everyday spending, Arbitrum with BRRR is enabling decentralized finance to meet traditional financial speed and certainty.


# Tether x BRRR — Native Multi‑network Settlement for Global Stablecoin Payments

[Tether’s](https://tether.io){rel="nofollow"} USD₮ is the world’s largest stablecoin by volume and market‑cap with over $160 B minted, it represents more than 60% of all stablecoins available onchain and now has non-USD options with EUR₮, CNH₮, MXN₮, as well as XAU₮. All Tether tokens are minted on a long list of public blockchains, including Tron, Ethereum, Solana, Avalanche, Polygon, TON, Plasma and more, so users can choose the network that best fits their fees, speed and tooling needs.

## What makes Tether stablecoins stand out

- Deep global liquidity: USDT alone clears hundreds of billions of dollars in daily transfer volume and is listed on virtually every crypto venue.
- Multi‑chain optionality: the same asset code (e.g. USDT) exists on more than a dozen chains, letting users move to the cheapest or fastest rail at any moment.
- Fiat & non‑USD flavours: launch of EUR₮ MiCA‑ready, MXN₮ for Latin America and CNH₮ for offshore CNY give local pricing without FX slippage.
- Asset‑backed diversification: XAU₮ gives tokenised access to vaulted gold while remaining interoperable with the rest of the Tether suite.

## The BRRR connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. Because USDT and sibling tokens already live on many chains, they are the native liquidity that BRRR’s routers search first when building a route.

## How BRRR enriches Tether settlement

|                          | What BRRR does behind the scenes                                                                                                                         | User / merchant experience                                                                    |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Cross‑chain payments     | Detects incoming USDT on Network 1, like Plasma, swaps/bridges to merchant‑preferred Network 2 to, like Solana in the same intent; finalises in seconds. | Merchant sees USDT arrive natively on Solana with no custody hop.                             |
| Card swipe in stablecoin | Converts POS authorisation in EUR into a just‑in‑time pull of USDT from the user’s wallet; BRRR relays FX+network fees to issuer, nets the rest in EUR₮. | User spends USDT anywhere Mastercard/Visa are accepted.                                       |
| On‑chain payroll         | Protocol sends one BRRR intent funding 50 wallets across five chains; protocol nets fees, executes swaps, pushes payouts.                                | Contributors choose any Tether variant (USDT, MXNT, XAU₮) and chain, get paid near‑instantly. |
| Gas-Free Experiences     | Relayers cover network gas, abstracting ERC‑20 “approve” and bridge messages.                                                                            | First‑time USDT users click once, pay nothing.                                                |

All steps are auditable: each BRRR intent produces a hash that proves which USDT‑TxID funded which off‑chain SEPA, ACH or card transaction, tightening compliance loops for both Tether and integrators.

## Real-world applications

### Point‑of‑sale settlement in emerging markets

A Lagos café prices in naira but settles in USDT on Tron; BRRR converts net proceeds to Nigerian bank NGN at day‑end, insulating the owner from FX shortages.

### B2B and B2C remittances

Designer invoices in MXN₮, client pays USDT on Polygon; BRRR auto‑swaps and deposits MXN to the worker’s Mexican bank via SPEI in under an hour.

### Instant chargebacks

If a buyer is refunded, BRRR reconstructs the original USDT route and pushes funds back to the buyer’s wallet on their chosen chain, avoiding multi‑day card reversals.

### Gold‑denominated savings

Users hold XAU₮ on Plasma as inflation hedge, BRRR lets them swipe a debit card that liquidates milligram‑sized pieces of gold in real time when paying in fiat.

## Who can benefit from BRRR

- Users keep self‑custody or use their balance of stablecoins yet pay like locals worldwide.
- Merchants & PSPs can accept one stablecoin rail instead of integrating many blockchains or liquidity providers.
- Tethers deeper utility drives token velocity and demand across every supported chain.
- BRRR stakers gain exposure to a rapidly expanding onchain FX market. The integration of Tethers ecosystem into BRRR's settlement layer allows holders of BRRR tokens to benefit from payment volume and fees generated by crosschain FX operations.


# Plasma x BRRR – Paying with stablecoins real time

[Plasma](https://www.plasma.to){rel="nofollow"} is a next-generation blockchain purpose-built for stablecoin transactions, fast, cost-efficient, and ready for real-world use. By integrating BRRR with Plasma, it results in programmable, cross-chain, fiat-connected payment workflows on a high-speed stablecoin network. The result: businesses and consumers can enjoy seamless real-time settlement in stablecoins across borders and at the point of sale.

## What makes Plasma stand out

- Plasma is a specialized Layer-1 blockchain designed for stablecoins from the ground up, and powers near instant, fee-free payments with institutional-grade security.
- Plasma’s mission is clear: make stablecoins as usable as cash in everyday commerce. It aims to bring stablecoin adoption to the next level, unlocking trillions in onchain volume by providing the speed, scalability, and low costs that legacy blockchains couldn’t offer.

## The BRRR connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. By integrating with Plasma, BRRR extends its programmable, cross-chain payment workflows onto a chain tailor-made for stablecoins. This integration means any stablecoin transaction on Plasma can plug into BRRR’s fiat-connected infrastructure, for example, automatically settling in fiat for a card payment or syncing with traditional payments and banking systems. BRRR x Plasma bridges the gap between stablecoins onchain and real-world fiat usage, enabling users and businesses on Plasma to transact globally with merchants in an instant, seamless manner.

## How Plasma enriches BRRR

1. Plasma’s ultra-efficient design slashes transaction costs – even enabling zero-fee stablecoin transfers. This cost advantage directly benefits BRRR-powered payments: whether it’s a micropayment or a large B2B transfer, fees are negligible, making stablecoin transactions economically viable at any scale.
2. Speed and finality: Plasma’s consensus finalizes transactions near-instantly with no risk of reversal. For BRRR, which emphasizes real-time clearing, this means a payment can be confirmed on Plasma in seconds and treated as settled, much like a cash transaction, but with the transparency of blockchain.

## Real-world applications

### ​Consumer spending

Users can pay for everyday purchases directly in stablecoins using BRRR-powered wallets or cards. Plasma processes these transactions instantly, with merchants receiving funds in fiat or stablecoins without volatility risk.

### Merchant settlement

Merchants and platforms can accept stablecoin payments with near-instant finality. BRRR automates conversion and reconciliation, while Plasma’s zero-fee stablecoin transfers make cross-border e-commerce and high-volume retail cost-efficient.

### Cross-border B2B & remittances

Businesses and individuals can send stablecoin payments globally in seconds. BRRR uses Plasma’s settlement layer to streamline payroll, supplier payments, and remittances with minimal fees and 24/7 availability.

### Fintech & institutional integrations

Banks and fintechs can integrate BRRR on Plasma to offer programmable stablecoin services, from treasury operations to subscription billing, leveraging instant, transparent, and compliant onchain-to-fiat flows.

## Who can benefit from BRRR

- Fintechs use Plasma and BRRR to access fast, purpose-built stablecoin rails for real-time payments, disbursements, and cross-border settlements with near-zero fees and instant finality.
- Protocols on Plasma benefit from BRRR as a programmable bridge to traditional finance, enabling stablecoin-native apps to support fiat payouts, card transactions, and real-world spending without leaving the chain.
- Institutions leverage BRRR and Plasma to settle global obligations in a compliant, cost-efficient, and transparent way unlocking seamless, onchain-to-fiat flows and programmable treasury operations at scale.

Whether it’s a remittance company moving funds across borders or a DeFi builder creating a stablecoin checkout service, those who have tapped into the Plasma × BRRR network are experiencing faster, simpler, and more reliable stablecoin transactions than ever.


# Starknet x BRRR – Real-time onchain settlement

[Starknet](https://www.starknet.io/){rel="nofollow"} is a blockchain platform built on StarkWare's technology, designed to provide scalable and secure transactions using zero-knowledge proofs. As a permissionless decentralized network, it enables developers to build and deploy complex applications while maintaining high performance and low costs.

## Key Features of Starknet

- STARK Proofs: Leverages advanced zero-knowledge proofs for secure and scalable transaction processing, inheriting Ethereum's security.
- High Scalability: Designed to handle high transaction volumes while maintaining low fees and fast processing times.
- Developer-Friendly: Offers comprehensive developer tools and Cairo programming language, making it easy to build complex applications.
- Ethereum Security: Inherits security from Ethereum while providing significantly higher throughput and lower costs.

You can read more about Starknet and its features in the [official documentation](https://docs.starknet.io/){rel="nofollow"}.

## The BRRR Connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. With Starknet integration, assets on Starknet can now be spent globally via BRRR at checkout, for payroll, or through direct transfers. BRRR protocol abstracts away blockchain complexity, enabling users to spend from Starknet while merchants or banks receive fiat instantly, unlocking compliant and seamless flows between onchain funds and real-world payments.

## How Starknet Enriches BRRR

1. Starknet introduces a new dimension of performance and flexibility to BRRR’s global payments infrastructure. Its ZK-rollup architecture enables transaction batching and compression, allowing BRRR to facilitate high-volume payments without network congestion or cost inflation.
2. With Cairo smart contracts, BRRR can build tailored logic for conditional payouts, recurring payments, and escrow-based releases. These features help automate treasury operations and make settlement programmable at scale.
3. Starknet’s native account abstraction improves user onboarding and transaction design. BRRR users benefit from advanced features, including fee subsidization and custom authorization flows, making it easier for fintechs and non-technical users to interact with crypto-fiat bridges.
4. As every transaction settles with Ethereum-grade security, BRRR on Starknet offers high-speed execution without compromising compliance or trust.

## Real-World Applications

### Consumer Spending

Users can pay with Starknet-based stablecoins at the checkout or online. BRRR handles instant onchain settlement, making the experience indistinguishable from traditional card payments.

### Cross-Border Transfers

Starknet enables businesses to fund large-scale stablecoin transfers globally. BRRR reconciles funds into local fiat accounts in real time, eliminating costly wire fees and delays.

### Programmable Finance

Smart contracts on Starknet can trigger real-world outcomes via BRRR, such as automatically distributing revenue shares or paying invoices when blockchain events occur.

### Fintech Integration

Apps and wallets can build intuitive fiat touchpoints directly into their UI by integrating BRRR on Starknet. Use cases include dynamic card funding, gasless transaction support, and seamless exits to IBAN or other traditional payment rails.

## Who can benefit from BRRR

- Fintechs use Starknet and BRRR to access fast, reliable crypto rails for spending, disbursements, and stablecoin settlements.
- Protocols on Starknet benefit from BRRR as an offchain bridge to traditional payments, enhancing the utility of DeFi-native assets.
- Institutions leverage BRRR and Starknet to settle real-world obligations in a compliant, cost-efficient, and programmable way, unlocking instant, onchain-to-fiat flows.

The Starknet × BRRR integration proves how real-world payments can operate on advanced blockchain infrastructure. Starknet provides the scale and security; BRRR provides the fiat bridge. Together, they enable stablecoins to move and settle instantly, compliantly, and globally, paving the way for seamless financial experiences across DeFi, fintech, and traditional payments.


# Solana x BRRR – Enabling Real‑Time Crypto Payments and Markets Efficiency

[Solana](https://solana.com/){rel="nofollow"} is a high-performance Layer 1 blockchain, known for its speed, low costs, and scalability. With an innovative Proof of Stake combined with a Proof of History consensus, Solana can process thousands of transactions per second with minimal fees. This makes Solana ideal for real-time payments and micropayments, where high throughput and low latency are crucial. BRRR has fully integrated with Solana to bring instant, fiat-connected stablecoin payments to one of the world's fastest blockchain networks. With sub-second block finality, negligible transaction costs, and growing adoption in traditional and DeFi finance, Solana is an ideal home for BRRR's programmable clearing layer. This integration enables seamless onchain-to-fiat and vice versa flows for users, merchants, institutions, and developers.

## What makes Solana stand out?

- Solana is purpose-built for speed, scale, and affordability. With block times of \~400ms, throughput exceeding 65,000 transactions per second, and average fees below $0.01, it is uniquely positioned to support stablecoin-powered payments.
- Solana's performance has already drawn interest from global players: Visa uses Solana to settle millions in stablecoin-based transactions, and payment integrations like Shopify Pay and Worldpay have joined its ecosystem. Combined with a robust developer stack and fast-growing user base, Solana provides the infrastructure required for real-time financial applications at scale.

## The BRRR connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and cross-chain swaps in a single transaction. BRRR enables live onramps, offramps, multi-asset support, wallet integration, and an SDK for developers to embed crypto-fiat flows into Solana's apps.

## How Solana enriches BRRR

1. Speed & scalability: Solana elevates BRRR's performance by introducing a unique blend of technical advantages and ecosystem accessibility. Its sub-second block times and massive throughput ensure BRRR-powered transactions execute nearly instantly, making them indistinguishable from conventional fiat payments. This performance is crucial for latency-sensitive use cases, including card payments, payroll, and dynamic commerce.
2. Cost-effectiveness: BRRR's stablecoin conversions and settlement operations become near-free, enabling use cases from micro-transactions to global disbursements. Solana chain's expansive liquidity and stablecoin presence create seamless pathways for multi-asset routing, empowering BRRR to optimize conversions and settlements across multiple assets.
3. Ecosystem reach & Developer support: Solana's growing network of wallets, stablecoins, and fintechs creates an ideal environment for BRRR's interoperable, fiat-connected primitives. Solana's EVM interoperability and robust Web3 infrastructure permit BRRR's SDK to plug into dApps, wallets, and fintech platforms with minimal friction.

## Real-world applications

### Consumer spending

Through Holyheld's card and wallet, users can spend Solana-based assets such as USDC and SOL at millions of merchants. Thanks to Solana's low latency and BRRR's clearing engine, the crypto-to-fiat conversion happens instantly at the point of sale, allowing users to retain self-custody until payment execution.

### Cross-border payroll and business payouts

Employers and platforms can pay contractors, employees, or vendors in stablecoins on the Solana. Using BRRR's offramps, these funds can settle as fiat in local bank accounts within seconds, streamlining operational cash flows for remote teams and gig platforms.

### Fintech integrations and developer tooling

Solana-based wallets and DeFi platforms can integrate BRRR's SDK to offer embedded fiat ramps, instant card top-ups, and payout APIs. These features enable any app to integrate global payment capabilities – from onchain-to-fiat withdrawal to dynamic card loading natively within their product experience.

## Who can benefit from BRRR

- Fintechs get with BRRR Solana access to power real-time, low-cost stablecoin disbursements, user payouts, and card-linked wallets.
- Solana protocols extend DeFi utility into traditional finance by incorporating BRRR for fiat payments, merchant acceptance, and compliant on- and offramps.
- Institutions settle global obligations on Solana with instant, onchain-to-fiat settlement using BRRR's reconciliation and ramp infrastructure.

Solana's high-speed blockchain and BRRR's programmable payment layer are transforming practical applications of digital assets. This integration demonstrates that stablecoins can move and settle cash instantly, globally, and transparently. Whether you're building a fintech app, running a DeFi protocol, or managing cross-border payments, Solana x BRRR is infrastructure ready for scale.


# Skale x BRRR – Gas‑Free Blockchain Innovation for DeFi and Global Payments

[Skale](https://skale.space/){rel="nofollow"} is a modular, Ethereum-native multichain network that eliminates gas fees for users while maximizing transaction speed and security. BRRR integration with Skale Network provides a programmable stablecoin settlement layer to a fast, composable, and cost-efficient blockchain. Together, Skale and BRRR enable developers, institutions, and fintechs to unlock seamless, compliant payment flows without the bottlenecks of legacy financial systems or traditional blockchain transaction costs.

## What makes Skale stand out?

- Skales’ design is centered around application-specific chains that run in parallel, each with its own resources and validator groups, eliminating congestion and enabling truly horizontal scalability.
- With hundreds of TPS per chain, near-instant finality, and full EVM compatibility, Skale allows developers to deploy highly performant smart contracts with no infrastructure burden.
- Built-in cross-chain messaging, onchain storage, and the liquidity hub ensure that assets and data can flow seamlessly across the Skale ecosystem.
- Skale’s FAIR protocol update adds MEV resistance and further strengthens consensus fairness, making it especially suitable for mission-critical financial applications.

## The BRRR connection

BRRR is a decentralized settlement layer designed to connect blockchain and traditional payment networks. It enables programmable clearing, reconciliation, and crosschain swaps in a single transaction. Skale’s zero-fee and instant-finality framework offers the optimal execution environment for BRRR’s operations. With Skale-based assets now fully integrated, BRRR allows its users and partners to initiate, process, and finalize financial activity on Skale without any delays, friction, or overhead, bringing instant value exchange into real-world usage.

## How Skale enriches BRRR

1. No user gas costs: By removing gas entirely from the user experience, BRRR-powered apps on Skale can deliver frictionless spending, top-ups, and disbursements.
2. Fast, final settlement: Sub-second block times and rapid finality allow BRRR to process transactions with the speed and confidence required by financial networks and card programs.
3. Chain-level customization: Skale’s modular architecture allows BRRR to launch dedicated chains tailored to payment logic, throughput, or compliance requirements.
4. Integrated liquidity and cross-chain tools: The Europa Hub allows BRRR to access uniform token standards and liquidity across Skale chains, simplifying asset flow and conversion.
5. Secure, compliant operations: MEV-resistant consensus and validator rotation mechanisms create a trust-minimized infrastructure suitable for high-integrity financial applications.

## Real-world applications

### Crypto debit card payments

Consumers can use Skale-based stablecoins at any merchant accepting Holyheld’s Visa cards. Funds are converted and settled in fiat instantly via BRRR.

### Payroll and remittances

Companies can distribute salaries and global vendor payments over Skale with stablecoins, while BRRR handles real-time conversion into fiat accounts.

### In-app financial services

Fintech platforms and wallets on Skale can embed BRRR to enable on-demand fiat withdrawals, dynamic card top-ups, or direct spending from onchain balances.

### DeFi on and offramps

Protocols on Skale can integrate BRRR to automatically convert earned yield or collateral into fiat at settlement, eliminating the need for users to bridge to enter or exit manually.

## Who can benefit from BRRR

- Fintechs and startups leverage Skale’s zero-gas chains to launch cost-efficient payment apps while relying on BRRR for settlement, compliance, and fiat integration.
- DeFi protocols on Skale gain access to seamless exits and fiat utility by embedding BRRR’s programmable offramps.
- Institutions using blockchain for treasury, disbursement, or digital asset custody benefit from BRRR’s ability to convert crypto to fiat in real-time, with no gas volatility.
- Consumers spend and move value on Skale without worrying about fees, complexity, or delays, thus enjoying near-instant crypto payments through a familiar user experience.

Skale’s unique zero gas architecture, modular chains, and instant finality make it one of the most capable blockchains for powering scalable, real-world financial applications. BRRR brings the programmable financial layer, fiat bridges, and regulatory alignment needed to translate blockchain activity into everyday value. Together, they form a comprehensive stack for next-generation payments: cost-effective, compliant, and fast enough to serve modern commerce at scale.


# Introduction

Holyheld SDK provides methods to on/off ramp crypto to and from Holyheld account in Typescript/Javascript environment. The process is split in only a few steps and allows you to customize customer flow and UI.

To use Holyheld SDK, you will require an **API key**. To obtain one, please reach out to your Holyheld point of contact.

> 🔔 Please note! Node.js polyfill is required

Some dependencies in SDK rely on Node.js’s Buffer class, which is not available by default in modern bundlers. To ensure compatibility, you must `polyfill` Buffer using one of the following:

- [buffer](https://github.com/feross/buffer){rel="nofollow"} - for manual importing
- [vite-plugin-node-polyfills](https://github.com/davidmyersdev/vite-plugin-node-polyfills){rel="nofollow"} - for `Vite`
- [node-polyfill-webpack-plugin](https://github.com/Richienb/node-polyfill-webpack-plugin){rel="nofollow"} - for `Webpack`
- [rollup-plugin-node-polyfills](https://github.com/ionic-team/rollup-plugin-node-polyfills){rel="nofollow"} - for `Rollup`

Please refer to your bundler’s documentation for setup instructions.

## Web3 Provider

The SDK supports both EVM compatible and Solana networks. Please see [examples](https://brrr.network/documentation/web3-providers) for more details.

### EVM Networks

A [Viem](https://github.com/wagmi-dev/viem){rel="nofollow"} provider is used for EVM-compatible JSON-RPC interactions, [Web3.js](https://github.com/web3/web3.js){rel="nofollow"} and [ethers.js](https://github.com/ethers-io/ethers.js){rel="nofollow"} are also supported.

### Solana

Solana is supported via [@solana/web3.js](https://github.com/solana-labs/solana-web3.js){rel="nofollow"}.


# Installation

To install Holyheld SDK using NPM:

```bash
$ npm install @holyheld/sdk
```

Using yarn:

```bash
$ yarn add @holyheld/sdk
```


# Initialization

To initialize the Holyheld SDK using your Holyheld API key:

```js
import HolyheldSDK from '@holyheld/sdk';

(async () => {
  const holyheldSDK = new HolyheldSDK({
    apiKey: process.env.HOLYHELD_SDK_API_KEY, // API key received upon validation and confirmation from Holyheld
  });

  await holyheldSDK.init();
})();
```


# Working with different Web3 providers

## EVM Networks

By default, a [viem](https://github.com/wagmi-dev/viem){rel="nofollow"} provider is used for EVM-compatible JSON-RPC interaction. However, you can use Holyheld SDK with other providers like Ethers.js and Web3.js.

### Wagmi

```js
import { getPublicClient, getWalletClient } from '@wagmi/core';

const chainId; // token chain id

(async () => {
  const publicClient = getPublicClient({ chainId });
  const walletClient = await getWalletClient({ chainId });
})();
```

### Ethers.js

```js
import { providers } from 'ethers';
import { createPublicClient, createWalletClient, custom, http } from 'viem';

const chain; // chain entity from viem

const provider = new providers.Web3Provider(window.ethereum);

const publicClient = createPublicClient({
  chain,
  transport: http(),
});

const walletClient = createWalletClient({
  chain,
  transport: custom(provider.provider),
  account: '0x...', // wallet address
});
```

### Web3.js

```js
import Web3 from 'web3';
import { createPublicClient, createWalletClient, custom, http } from 'viem';

const chain; // chain entity from viem

const provider = new Web3(window.ethereum).currentProvider;

const publicClient = createPublicClient({
  chain,
  transport: http(),
});

const walletClient = createWalletClient({
  chain,
  transport: custom(provider),
  account: '0x...', // wallet address
});
```

## Solana Network

To interact with the Solana network, Holyheld SDK requires two things: a connection to the network and a wallet client.

### Connection

The `Connection` object is part of the [@solana/web3.js](https://github.com/solana-labs/solana-web3.js){rel="nofollow"} library and is responsible for all communication with the Solana network.

```js
import { Connection, clusterApiUrl } from '@solana/web3.js';

const networkInfo = sdk.solana.getNetwork(SolanaNetwork.Mainnet);

const connection = new Connection(networkInfo.httpRpcURL, {
  commitment: 'confirmed',
  wsEndpoint: networkInfo.wsRpcURL ?? clusterApiUrl(networkInfo.cluster, true)
});
```

### Wallet client

The wallet client must implement the following interface expected by the SDK:

```typescript
import { type SendOptions, VersionedTransaction } from '@solana/web3.js';

interface WalletClientSolana {
  signMessage(message: string): Promise<string>;
  signTransaction(transaction: VersionedTransaction): Promise<VersionedTransaction>;
  signAllTransactions?(transactions: Array<VersionedTransaction>): Promise<Array<VersionedTransaction>>;
  signAndSendTransaction(transaction: VersionedTransaction, sendOptions?: SendOptions): Promise<string>;
}
```

You can implement this interface manually, or use one of the [wallet adapters](https://github.com/anza-xyz/wallet-adapter){rel="nofollow"}. The SDK provides a helper function to wrap such adapters into the required format.

For example, `PhantomWalletAdapter`:

```js
import { Connection } from '@solana/web3.js';
import { PhantomWalletAdapter } from '@solana/wallet-adapter-phantom';
import { createSolanaWalletClientFromAdapter } from '@holyheld/sdk';

const walletAdapter = new PhantomWalletAdapter();

const connection = new Connection(/* ... */);

const walletClient = createSolanaWalletClientFromAdapter(walletAdapter, connection);
```


# Offramp Flow

To offramp to a Holyheld account the following steps should be completed:

1. Get settings and ensure that offramping is available using `getServerSettings` method.
2. Check that selected wallet or holytag can transact using methods: `validateAddress` for a wallet or `getTagInfo` for a $holytag.
3. Provide two parameters: token and amount.
4. Get binary data to pass as swap parameters using `convertTokenToEUR` or `convertEURToToken` methods.
5. Call the `topup` method to execute the transaction.

> 🔔 Please note! If multiple wallet interactions are required (e.g. signing allowance and executing a transaction, or permit signing and executing a transaction) they will be processed automatically.

6. Wait for the transaction hash of the operation to be received.

There are six functions available to use:

- `getServerSettings` - to get server settings.
- `validateAddress` - to get wallet information.
- `getTagInfo` - to get holytag information.
- `convertTokenToEUR` - to get a EUR quote for a specific amount of tokens.
- `convertEURToToken` - to get a a token quote for a specific amount of EUR.
- `topup` - to execute offramp.

## `getServerSettings` Get settings

This method gets current state/settings when interacting with the service. Please always use this method to check:

- if the feature is available;
- the minimum and maximum allowed amounts to offramp.

> 🔔 Please note! Financial values are provided and consumed as strings to avoid floating point conversion problems.

```js
(async () => {
  const data = await holyheldSDK.getServerSettings();
})();
```

Types:

```typescript
type ServerExternalSettings = {
  external: {
    isTopupEnabled: boolean; // indicates if offramp is available at the moment
    isOnRampEnabled: true; // indicates if onramp is available at the moment
    maxTopUpAmountInEUR: string; // maximum amount (equivalent in EUR) that is allowed to be processed, for example: '1000'
    minTopUpAmountInEUR: string; // minimum amount (equivalent in EUR) that is allowed to be processed, for example '5'
    maxOnRampAmountInEUR: string; // maximum amount in EUR that is allowed to be processed, for example: '1000'
    minOnRampAmountInEUR: string; // minimum amount in EUR that is allowed to be processed, for example: '5'
  };
  common: {
    topUpFeePercent: string; // fee (in percent) that is deducted when making an offramp operation, for example: '0.75'
  };
}
```

## `validateAddress` Get wallet information

User wallet address is a unique identifier which can have account, card and a $holytag bound to it. It is alphanumeric string. Wallet address must be a valid EVM (0x..., 42 chars) or Solana (Base58, \~32–44 chars) address.

> 🔔 Please note! Ethereum Name Service (ENS) and Solana Name Service (SNS) domains are not supported.

```js
(async () => {
  const evmAddressData = await holyheldSDK.validateAddress('0x000000000000000000000000000000000000dEaD'); // a wallet address could be preset or have to be entered by user, depends on what user flow you as a developer want to set

  const solanaAddressData = await holyheldSDK.validateAddress('14grJpemFaf88c8tiVb77W7TYg2W3ir6pfkKz3YjBRRR'); // same example for a Solana wallet address
})();
```

Types:

```typescript
type ValidateAddressResult = {
  isTopupAllowed: boolean;
  isOnRampAllowed: boolean;
}
```

## `getTagInfo` Get tag information

$holytag is a unique identifier which can have account, card and multiple Ethereum and/or Solana addresses bound to it. $holytag is alphanumeric string with a few special characters allowed. A valid holytag can be as short as one (1) and as long as thirty one (31) characters.

> 🔔 Please note! The only two special characters allowed are: dash `-` and underscore `_`.

$holytag is usually displayed prepended with a `$` prefix, for example: $JohnSmith holytag is `JohnSmith` or $PEPE holytag `PEPE`, etc.

Tags are stored case-sensitive for display, but not case-sensitive for search, and are not allowed to have multiple case variants registered. It means that if there is a holytag `$ToTheMoon` registered, other case sensitive variations are not allowed (e.g. `$toTHEmoon`).

### Test $holytag

You can use `SDKTEST` as a test $holytag. All transactions to this $holytag will **NOT** trigger an actual fiat-corresponding transaction, but will return a fully valid response. There is no minimum amount set for the test $holytag. `SDKTEST` test $holytag works across all supported networks and tokens.

> 🔔 Please note! Funds from test transactions to `SDKTEST` can **NOT** be retrieved. Do not initiate large test transactions.

```js
(async () => {
  // a tag name could be preset by the developer (you) or inputted by the user. It depends on the user flow you want to have
  const data = await holyheldSDK.getTagInfo('SDKTEST');
})();
```

Types:

```typescript
type TagInfo = {
  found: boolean; // if the holytag exists and active
  tag?: string; // holytag name (case sensitive, as registered), for example: 'SDKTEST'
  avatarSrc?: string; // if set, a link to avatar image, for example example: 'https://holyheld.com/static/avatar.png'
}
```

## `getWalletBalances` Get wallet balances

You can use `getWalletBalances` method to retrieve all tokens on the connected user wallet address. The full list of supported networks is [here](https://holyheld.com/faq/frequently-asked-questions/supported-networks){rel="nofollow"}.

### EVM Networks

```js
(async () => {
  const data = await holyheldSDK.evm.getWalletBalances(
    '0x...', // user wallet address
  );
})();
```

Types:

```typescript
import { Network } from '@holyheld/sdk';

type WalletTokenEVM = {
  name: string; // name of the token, for example: 'USD Coin'
  address: string; // smart contract address of the token, for example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
  symbol: string; // token symbol, for example: 'USDC'
  decimals: number; // token decimal digits (as in ERC20 implementation), for example: 6
  network: Network; // network (blockchain), on which this token resides
  networkKind: NetworkKind // blockchain type
  iconURL: string; // logo (icon) for the token
  priceUSD: string; // current estimated price (in USD), for example: '1796.55'
  balance: string; // amount of token in the user's wallet, for example: '0.0000099999999'
  priceInEURForTopUp: string; // token price converted from USD to EUR, for example: '1726.53'
  meta: {
    permitData: {
      hasPermit: boolean; // if the token supports permit signatures
      permitType?: string; // type of permit signature, 'erc2612' is expected
      permitVersion?: string; // permit version (currently, if permit supported, '1' is expected)
    }
  }
};

type WalletBalancesEVM = {
  tokens: WalletTokenEVM[];
}
```

### Solana Network

```js
(async () => {
  const data = await holyheldSDK.solana.getWalletBalances(
    '...', // user wallet address
  );
})();
```

Types:

```typescript
import { Network } from '@holyheld/sdk';

type WalletTokenSolana = {
  name: string; // name of the token, for example: 'Solana'
  decimals: number; // token decimal digits, for example: '9'
  address: string; // smart contract address of the token, for example: 'So11111111111111111111111111111111111111112'
  symbol: string; // token symbol, for example: 'SOL'
  network: SolanaNetwork; // network (blockchain), on which this token resides
  networkKind: NetworkKind.Solana // blockchain type
  iconURL: string; // logo (icon) for the token
  priceUSD: string; // example: '1796.55'  // current estimated price (in USD)
  balance: string; // amount of token in the user's wallet, for example: '0.0000099999999'
  priceInEURForTopUp: string; // token price converted from USD to EUR, for example: '1726.53'
  meta: {
    tokenProgramId?: string; // SPL token program address (usually the standard TokenkegQfeZyi...)
  }
};

type WalletBalancesSolana = {
  tokens: WalletTokenSolana[];
}
```

## `convertTokenToEUR` token to EUR quote

This method is used to estimate a token value in EUR to proceed with the offramping. `convertTokenToEUR` method can also be used in some scenarios/apps where token to be sent is preset and not selectable.

This method also returns `transferData` — a hexadecimal string which can contain token-specific transfer, unwrap or swap data that is passed in an offramp transaction.

### EVM Networks

```js
import { Network } from '@holyheld/sdk';

(async () => {
  const data = await holyheldSDK.evm.offRamp.convertTokenToEUR({
    walletAddress: '0x...', // wallet address
    tokenAddress: '0x...', // token address
    tokenDecimals: 6, // token decimals
    amount: '9.99', // token amount
    network: Network.ethereum, // token network
  });
})();
```

Types:

```typescript
import type { TransferDataEVM } from '@holyheld/sdk';

type ConvertTopUpDataEVM = {
  tokenAmount: string; // amount of token that was passed to query, for example: '1.99'
  EURAmount: string; // EUR valuation of the token amount provided, for example: '314.25'
  transferData?: TransferDataEVM; // data to be passed in sending transaction for this specific token (and amount)
}
```

### Solana Network

```js
import { SolanaNetwork } from '@holyheld/sdk';

(async () => {
  const data = await holyheldSDK.solana.offRamp.convertTokenToEUR({
    walletAddress: '...', // wallet address
    tokenAddress: '...', // token address
    tokenDecimals: 6, // token decimals
    amount: '9.99', // token amount
    network: SolanaNetwork.Mainnet, // token network
  });
})();
```

Types:

```typescript
import type { TransferDataSolana } from '@holyheld/sdk';

type ConvertTopUpDataSolana = {
  tokenAmount: string; // amount of token that was passed to query, for example: '1.99'
  EURAmount: string; // EUR valuation of the token amount provided, for example: '314.25'
  transferData?: TransferDataSolana; // data to be passed in sending transaction for this specific token (and amount)
}
```

## `convertEURToToken` EUR to token quote

`convertEURToToken` method returns a calculated token amount to match provided (expected) EUR amount.

This method also returns `transferData`, that is hexadecimal string which could contain token-specific transfer, unwrap or swap data that is passed in sending to tag transaction.

### EVM Networks

```js
import { Network } from '@holyheld/sdk';

(async () => {
  const data = await holyheldSDK.evm.offRamp.convertEURToToken({
    walletAddress: '0x...', // wallet address
    tokenAddress: '0x...', // token address
    tokenDecimals: 6, // token decimals
    amount: '9.99', // token amount
    network: Network.ethereum, // token network
  });
})();
```

Types:

```typescript
import type { TransferDataEVM } from '@holyheld/sdk';

type ConvertTopUpDataEVM = {
  EURAmount: string; // amount (in EUR) that was passed to query, for example: '30.00'
  tokenAmount: string; // token amount to match expected valuation, for example: '4.18'
  transferData?: TransferDataEVM; // data to be passed in sending transaction for this specific token (and amount)
}
```

### Solana Network

```js
import { Network } from '@holyheld/sdk';

(async () => {
  const data = await holyheldSDK.solana.offRamp.convertEURToToken({
    walletAddress: '0x...', // wallet address
    tokenAddress: '0x...', // token address
    tokenDecimals: 6, // token decimals
    amount: '9.99', // token amount
    network: SolanaNetwork.Mainnet, // token network
  });
})();
```

Types:

```typescript
import type { TransferDataSolana } from '@holyheld/sdk';

type ConvertTopUpDataSolana = {
  tokenAmount: string; // amount of token that was passed to query, for example: '1.99'
  EURAmount: string; // EUR valuation of the token amount provided, for example: '314.25'
  transferData?: TransferDataSolana; // data to be passed in sending transaction for this specific token (and amount)
}
```

## Offramp

This is the 'main' method to call that executes offramping to the user card. Parameter values should be retrieved using methods described above, such as `transferData` matching token and token amount provided.

### EVM Networks

> 🚨 Please note! Some wallets like Metamask are single-network handled. It means that while Holyheld can return/accept transaction on any supported network, user **must** switch to the correct network in the wallet for the transaction to be processed.

```js
import { Network } from '@holyheld/sdk';
import * as chains from 'viem/chains';
import { createPublicClient, createWalletClient, custom, http } from 'viem';

const provider; // current provider in your app (see examples below)
const transferData; // transfer data from conversion methods or undefined
const eventConfig; // callbacks
const chainId; // token chain id

const chain = Object.values(chains).find((item) => item.id === chainId); // get chain entity from viem

const publicClient = createPublicClient({ // create viem public client - https://viem.sh/docs/clients/public.html
  chain,
  transport: http(),
});

const walletClient = createWalletClient({ // wrap your provider in viem wallet client - https://viem.sh/docs/clients/wallet.html
  chain,
  transport: custom(provider), // current provider in your app (see examples below)
  account: '0x...', // wallet address
});

(async () => {
  await holyheldSDK.evm.offRamp.topup({
    publicClient: publicClient,
    walletClient: walletClient,
    walletAddress: '0x...',
    tokenAddress: '0x...',
    tokenNetwork: Network.ethereum,
    tokenAmount: '5.25',
    transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
    holytag: 'SDKTEST', // funds recipient tag
    supportsSignTypedDataV4: true, // true if connected wallet supports eth_signTypedData_v4 (default: false)
    supportsRawTransactionsSigning: true, // true if connected wallet supports raw transactions signing via "eth_sign" or "eth_signTransaction"
    eventConfig: eventConfig, // callbacks (see below)
  });
})();
```

Types:

```typescript
enum TopUpStep {
  Confirming = 'confirming', // user is confirming action
  Approving = 'approving', // a request was sent to wallet for approval or permit signature
  Sending = 'sending', // a request was sent to wallet for executing sending funds to a tag
}

interface TopUpCallbackConfig {
  onHashGenerate?: (hash: string) => void;
  onStepChange?: (step: TopUpStep) => void;
}
```

### Solana

```js
import { Connection, clusterApiUrl } from '@solana/web3.js';
import { PhantomWalletAdapter } from '@solana/wallet-adapter-phantom';
import { SolanaNetwork, createSolanaWalletClientFromAdapter } from '@holyheld/sdk';


const transferData; // transfer data from conversion methods or undefined
const eventConfig; // callbacks

const networkInfo = holyheldSDK.solana.getNetwork(SolanaNetwork.Mainnet);

const connection = new Connection(networkInfo.httpRpcURL, {
  commitment: 'confirmed',
  wsEndpoint: networkInfo.wsRpcURL ?? clusterApiUrl(networkInfo.cluster, true)
});

const walletAdapter = new PhantomWalletAdapter();

const walletClient = createSolanaWalletClientFromAdapter(walletAdapter, connection);

(async () => {
  await holyheldSDK.solana.offRamp.topup({
    connection: connection,
    walletClient: walletClient,
    walletAddress: '...',
    tokenAddress: '...',
    tokenNetwork: SolanaNetwork.Mainnet,
    tokenAmount: '5.25',
    transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
    holytag: 'SDKTEST', // funds recipient tag
    eventConfig: {}, // callbacks (see below)
  });
})();
```

Types:

```typescript
enum TopUpStep {
  Confirming = 'confirming', // user is confirming action
  Sending = 'sending', // a request was sent to wallet for executing sending funds to a tag
}

interface TopUpCallbackConfig {
  onHashGenerate?: (hash: string) => void;
  onStepChange?: (step: TopUpStep) => void;
}
```


# Onramp Flow

To onramp from a Holyheld account the following steps should be completed:

1. Get settings and ensure that onramping is available using `getServerSettings` method.
2. Check that selected wallet can transact using `validateAddress` method.
3. Provide two parameters: token and amount in EUR.
4. Optional. Get binary data to pass as swap parameters using `convertEURToToken` or `convertTokenToEUR` methods.
5. Optional. Get an estimation of the network fee and the final token amount using `getOnRampEstimation` method.
6. Call the `requestOnRamp` method to execute the transaction.

> 🔔 Please note! User will need to confirm the onramp request in their Holyheld app

7. Wait for the callback response of the operation result using `watchRequestId`.

There are six functions available to use:

- `getServerSettings` - to get server settings.
- `validateAddress` - to get wallet information.
- `convertEURToToken` - to get a a token quote for a specific amount of EUR.
- `convertTokenToEUR` - to get a EUR quote for a specific amount of tokens.
- `getOnRampEstimation` - to get an onramp estimation.
- `requestOnRamp` - to execute onramp.

## `getServerSettings` Get settings

This method gets current state/settings for interacting with the service. Please always use this method to check:

- if the feature is available;
- the minimum and maximum allowed amounts to onramp.

> 🔔 Please note! Financial values are provided and consumed as strings to avoid floating point conversion problems.

```js
(async () => {
  const data = await holyheldSDK.getServerSettings();
})();
```

Types:

```typescript
type ServerExternalSettings = {
  external: {
    isTopupEnabled: boolean; // indicates if off-ramp is available at the moment
    isOnRampEnabled: true; // indicates if onramp is available at the moment
    maxTopUpAmountInEUR: string; // maximum amount (equivalent in EUR) that is allowed to be processed, for example: '1000'
    minTopUpAmountInEUR: string; // minimum amount (equivalent in EUR) that is allowed to be processed, for example: '5'
    maxOnRampAmountInEUR: string; // maximum amount in EUR that is allowed to be processed, for example: '1000'
    minOnRampAmountInEUR: string; // minimum amount in EUR that is allowed to be processed, for example: '5'
  };
  common: {
    topUpFeePercent: string; // fee (in percent) that is deducted when making an onramp operation, for example: '0.75'
  };
}
```

## `validateAddress` Get wallet information

User wallet address is a unique identifier which can have account, card and a $holytag bound to it. It is alphanumeric string. Wallet address must be a valid EVM (0x..., 42 chars) or Solana (Base58, \~32–44 chars) address.

> 🔔 Please note! Ethereum Name Service (ENS) and Solana Name Service (SNS) domains are not supported.

```js
(async () => {
  const evmAddressData = await holyheldSDK.validateAddress('0x000000000000000000000000000000000000dEaD'); // a wallet address could be preset or have to be entered by user, depends on what user flow you as a developer want to set

  const solanaAddressData = await holyheldSDK.validateAddress('14grJpemFaf88c8tiVb77W7TYg2W3ir6pfkKz3YjBRRR'); // same example for a Solana wallet address
})();
```

Types:

```typescript
type ValidateAddressResult = {
  isTopupAllowed: boolean;
  isOnRampAllowed: boolean;
}
```

## `convertTokenToEUR` Convert token to EUR

This method is used to estimate a token value in EUR to proceed with the onramping. `convertTokenToEUR` method can also be used in some scenarios/apps where token to be sent is preset and not selectable.

### EVM Networks

```js
(async () => {
  const data = await holyheldSDK.evm.onRamp.convertTokenToEUR(
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network of the token
    '11.11' // native token amount
  );
  console.log('EUR amount is', data)
})();
```

## `convertEURToToken` Convert EUR to token

`convertEURToToken` method returns a calculated token amount to match requested EUR amount.

### EVM Networks

```js
(async () => {
  const data = await holyheldSDK.evm.onRamp.convertEURToToken(
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network of the token
    '11.11' // EUR amount
  );
  console.log('token amount is', data)
})();

```

## `getOnRampEstimation` Estimate the network fee and the final token amount

`getOnRampEstimation` method returns the network fee in EUR and the final token amount.

### EVM Networks

```js
(async () => {
  const data = await holyheldSDK.evm.onRamp.getOnRampEstimation(
    '0x...', // user wallet address
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token
    Network.ethereum, // network where tokens will arrive
    '1' // amount in EUR
  );
})();
```

Types:

```typescript
type EstimateOnRampResult = {
  feeAmount: string; // network fee in EUR
  expectedAmount: string; // expected amount of the token excluding network fee
}
```

## `requestOnRamp` Created onramp transaction request

This is the 'main' method to call that executes onramping from a Holyheld account.

> 🚨 Please note! As per security requirements, the user **must** approve the onramp request in their Holyheld mobile app within 3 minutes. If the user declines, or lets the confirmation expire -- the transaction will fail and will not be executed.

### EVM Networks

```js
(async () => {
  const data = await holyheldSDK.evm.onRamp.requestOnRamp(
    '0x...', // user wallet address
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // address of the token to arrive
    Network.ethereum, // network where tokens will arrive
    '1' // amount in EUR
  );
})();
```

Types:

```typescript
type RequestOnRampResult = {
  requestUid: string; // ID of the onramp request created
  chainId: number; // ID of the network where tokens will arrive
  token: Token; // Address of the token to arrive
  amountEUR: string; // amount of EUR charged from the user
  amountToken: string; // native amount of tokens received
  feeEUR: string; // network gas fee charged from the total transaction amount
  beneficiaryAddress: Address; // user wallet address where tokens will arrive
}
```

After creating the onramp request, user will need to confirm it in their Holyheld app.

## `watchRequestId` Watch the onramp request by ID

This method is used to await for the request outcome based on the user confirmation or rejection in the Holyheld app. There are only three possible outcomes of any request:

1. `{ success: true }` or `{ success: true, hash: '0x...' }` if the request has been confirmed by the user and processed
2. `{ success: false }` if the request has been declined by the user
3. An error if request was not processed, timed out, or HTTP request was not returned as `OK`

```js
(async () => {
  const data = await holyheldSDK.evm.onRamp.watchRequestId(
    requestUid, // request ID from response for the requestOnRamp method
    options // optional
  );
})();
```

Types:

```typescript
type WatchOnRampRequestIdOptions = {
  timeout?: number; // timeout in ms
  waitForTransactionHash?: boolean;
};

type WatchOnRampResult = {
  success: boolean; // successful or not
  hash?: string; // transaction hash. Present if "waitForTransactionHash" is true in request options and "success" is true
}
```


# Utilities

You can use the utilities to work with networks that the SDK supports.

## EVM Networks

```js
import { Network } from '@holyheld/sdk';

holyheldSDK.evm.offRamp.getAvailableNetworks(); // ['ethereum', 'polygon', ...]
holyheldSDK.evm.onRamp.getAvailableNetworks(); // ['ethereum', 'polygon', ...]
holyheldSDK.evm.isEVMNetwork(Network.ethereum); // true
holyheldSDK.evm.getNetwork(Network.ethereum); // NetworkInfoEVM
holyheldSDK.evm.getNetworkChainId(Network.ethereum); // 1
holyheldSDK.evm.getNetworkByChainId(1); // NetworkInfoEVM | undefined

(async () => {
  const value = await holyheldSDK.evm.offRamp.getTopUpEstimation({ // estimate transaction cost (only supports estimation for native tokens used for gas fees)
    publicClient: publicClient, // create public client, see https://viem.sh/docs/clients/public.html
    network: Network.ethereum,
    amount: '5.25', // token amount
    walletAddress: '0x...', // wallet address
    supportsSignTypedDataV4: true, // true if connected wallet supports 'eth_signTypedData_v4' (default: false)
    supportsRawTransactionsSigning: true, // true if connected wallet supports raw transactions signing via 'eth_sign' or 'eth_signTransaction' (default: false)
  });

  console.log(value); // '287499997500000' (in WEI)
})();
```

Types:

```typescript
type TokenEVM = {
  address: string; // smart contract address of the token
  decimals: number; // token decimal digits (as in ERC20 implementation)
  symbol: string; // token symbol
  network: Network; // network (blockchain), on which this token resides
  name: string; // name of the token
  iconURL: string; // logo (icon) for the token
  networkKind: NetworkKind.EVM // blockchain type
};

type NetworkInfoEVM = {
  network: Network;
  name: string; // name of the blockchain network, for example: 'Polygon Mainnet'
  chainId: number; // chainId of the corresponding network, for example: 137
  explorerURL: string; // block explorer URL of corresponding network, for example: 'https://polygonscan.com'
  explorerName: string; // block explorer name (e.g. to display user friendly link 'view on X'), for example: 'Polygonscan'
  baseAsset: TokenEVM; // base asset (native/gas token) of the network
  rpcUrls: string[]; // RPC URLs array (array supported for redundancy purposes), for example: ['https://polygon-rpc.com/'']
  iconURL: string; // logo (icon) for the network, displayed near token logo to identify on which network the token is on
  displayedName: string; // name of the network to display, for example: 'Polygon'
  orderIdx: number; // id for sorting, example: 1
  networkKind: NetworkKind.EVM // blockchain type
};
```

## Solana Network

```js
import { SolanaNetwork } from '@holyheld/sdk';

holyheldSDK.solana.offRamp.getAvailableNetworks(); // ['solana-mainnet']
holyheldSDK.solana.isSolanaNetwork(SolanaNetwork.Mainnet); // true
holyheldSDK.solana.getNetwork(SolanaNetwork.Mainnet); // NetworkInfoSolana

(async () => {
  // estimate transaction price
  const value = await holyheldSDK.solana.offRamp.getTopUpEstimation({
    connection: connection, // create connection, see https://solana-foundation.github.io/solana-web3.js/classes/Connection.html#constructor
    walletAddress: '...', // wallet address
    tokenAddress: '...', // token address
    tokenNetwork: SolanaNetwork.Mainnet,
    tokenAmount: '5.25', // token amount
    holytag: 'SDKTEST', // funds recipient tag
    transferData: transferData, // if was provided by 'convertTokenToEUR' and/or 'convertEURToToken'
  });

  console.log(value); // '229309' (in lamports)
})();
```

Types:

```typescript
type TokenSolana = {
  address: string; // smart contract address of the token
  decimals: number; // token decimal digits
  symbol: string; // token symbol
  network: SolanaNetwork; // network (blockchain), on which this token resides
  name: string; // name of the token
  iconURL: string; // logo (icon) for the token
  networkKind: NetworkKind.Solana // blockchain type
};

type NetworkInfoSolana = {
  network: SolanaNetwork;
  name: string; // name of the blockchain network, for example: 'Solana Mainnet'
  explorerURL: string; // block explorer URL of corresponding network, for example: 'https://solscan.io'
  explorerName: string; // block explorer name (e.g. to display user friendly link 'view on X'), for example: 'Solscan'
  baseAsset: TokenSolana; // base asset (native/gas token) of the network
  httpRpcURL: string; // HTTP RPC endpoint, for example: 'https://solana-rpc.publicnode.com'
  wsRpcURL: string; // WebSocket RPC endpoint, for example: 'wss://solana-rpc.publicnode.com'
  iconURL: string; // logo (icon) for the network, displayed near token logo to identify on which network the token is on
  displayedName: string; // name of the network to display, for example: 'Solana'
  orderIdx: number; // id for sorting, for example: 1
  networkKind: NetworkKind.Solana // blockchain type
};
```


# Error handling

Some errors have a class `HolyheldSDKError`. The most helpful property of these errors is code. You can compare the code with the values in the `HolyheldSDKErrorCode`.

```js
import { HolyheldSDKError, HolyheldSDKErrorCode } from '@holyheld/sdk';

const holyheldSDK = new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
})

(async () => {
  try {
    await holyheldSDK.evm.offRamp.topup(/* ... */);
  } catch (error) {
    if (
      error instanceof HolyheldSDKError &&
      (error.code === HolyheldSDKErrorCode.UserRejectedTransaction ||
        error.code === HolyheldSDKErrorCode.UserRejectedSignature)
    ) {
      // it's OK
    } else {
      // it's NOT OK
    }
  }
})();
```

Types:

```typescript
enum HolyheldSDKErrorCode {
  NotInitialized = 'HSDK_NI', // SDK is not initialized
  FailedInitialization = 'HSDK_FI', // cannot initialize SDK
  UnsupportedNetwork = 'HSDK_UN', // wallet active network is not supported by SDK
  InvalidTopUpAmount = 'HSDK_ITUA', // amount does not meet minimum or maximum allowed criteria
  InvalidOnRampAmount = 'HSDK_IORA', // amount does not meet minimum or maximum allowed criteria
  UnexpectedWalletNetwork = 'HSDK_UWN', // wallet active network is different from the selected network
  UserRejectedSignature = 'HSDK_RS', // user rejected the signature
  UserRejectedTransaction = 'HSDK_RT', // user rejected transaction
  FailedSettings = 'HSDK_FS', // cannot get settings
  FailedTagInfo = 'HSDK_FTI', // cannot get $holytag info
  FailedAddressInfo = 'HSDK_FAI', // cannot get address info
  FailedWalletBalances = 'HSDK_FWB', // cannot get wallet balance
  FailedConversion = 'HSDK_FC', // cannot estimate EUR to TOKEN, or TOKEN to EUR
  FailedTopUp = 'HSDK_FTU', // cannot complete top up
  FailedCreateOnRampRequest = 'HSDK_FCOR', // cannot create onramp request
  FailedOnRampRequest = 'HSDK_FOR', // fail execute onramp request with reason (for example not enough balance)
  FailedWatchOnRampRequestTimeout = 'HSDK_FwORT', // watch request timeout
  FailedWatchOnRampRequest = 'HSDK_FWORR', // fail to watch request status
  FailedConvertOnRampAmount = 'HSDK_FCORA', //cannot convert (estimate) EUR to TOKEN, or TOKEN to EUR
  FailedOnRampEstimation = 'HSDK_FCORA', // cannot estimate the network fee amount and the final token amount
}
```


# Logging

Logs are disabled by default. If you're debugging an application, set the `logger` option to `true`.

```js
new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
  logger: true,
})
```

You may also set a custom logger:

```js
new HolyheldSDK({
  apiKey: process.env.HOLYHELD_SDK_API_KEY,
  logger: (level, message, data) => {
    console.log(level, message, data);
  },
})
```

Types:

```typescript
enum LogLevel {
  Warning = 'warning',
  Log = 'log',
  Info = 'info',
  Debug = 'debug',
}

type Logger = (
  level: LogLevel, // level of event to be logged
  message: string, // message to be logged
  data?: { [key: string]: any }, // optional structured payload to be logged
) => void;
```


# Examples

There are some ready examples with open source code, they can be found in the [examples directory](https://github.com/holyheld/hh-v1-sdk/tree/master/examples){rel="nofollow"}. These are minimal html/javascript applications to illustrate the flow.

There are also already deployed demo versions available below.

## EVM Networks

### Offramp

- wagmi: <https://sdk-example-wagmi.holyheld.com/>{rel="nofollow"}
- ethers.js: <https://sdk-example-ethers-v5.holyheld.com/>{rel="nofollow"}
- web3.js: <https://sdk-example-web3.holyheld.com/>{rel="nofollow"}

A minimalistic version of the offramp SDK implementation for EVM networks can be found [here](https://holyheld.com/sdk/send){rel="nofollow"}.

### Onramp

- <https://sdk-example-wagmi-on-ramp.holyheld.com/>{rel="nofollow"}

## Solana

### Offramp

- <https://sdk-example-solana.holyheld.com/>{rel="nofollow"}


# Testing

A special $holytag was created for testing purposes: `$SDKTEST`. This is a special $holytag as it does not have minimum amount restrictions that regular $holytags do. Any onchain transaction to `$SDKTEST` will **NOT** trigger a corresponding fiat offramp transaction, but the application, backend and smart contract interactions will be executed as they would during the regular flow.

It is advised to use the test tag `$SDKTEST` with small amounts of tokens (less than $0.1) on networks with low network gas fees (Arbitrum, Polygon, Avalanche, Solana etc.) to avoid gas costs while performing the tests, ensuring correct live execution of the offramp.

> 🔔 Please note! Funds from test transactions to `SDKTEST` can **NOT** be retrieved. Do not initiate large test transactions.