Stablesats is a part of the blink OSS banking stack.
It enables users that deposit Bitcoin to hold a USD denominated value in their wallets.
It achieves this by identifying transactions that involve a hard-coded dealer
ledger account in the blink ledger and calculating a target liability.
This liability is subsequently hedged via shorting perpetual swap contracts on the okex exchange.
The code is organized into multiple crates. Some of the crates represent heplers or client libraries for the APIs we depend on and some of them represent logical units that can be run either in isolated processes or together with other units within the same process depending on config settings.
Communication between the (potentially distributed) processes happens via a pubsub system (currently Redis). Like this we can run multiple copies of the processes to achieve high-availability, fault tolerance and scalability.
The main modules that can be run via the cli are:
okex-price
: Module that streams price information from okex onto the pubsubprice-server
: Module that exposes a grpc endpoint for clients to get up-to-date price information (cached from the pubsub messages coming fromokex-price
).user_trades
: Module that identifies how much the total usd liability exists in the blink accounting ledger. It publishes theSynthUsdLiabilityPayload
message for downstream trading modules to pick up.hedging
: Module that executes trades on okex to match the target liability received from the pubsub.
Purpose: Connects to the Galoy banking backend (which powers Blink wallet) to monitor user transactions of the dealer-account and calculates the target liability balances.
How transaction polling works:
- GraphQL endpoint: Uses the
StablesatsTransactionsList
query against Blink's GraphQL API of the dealer account - Cursor-based pagination: Uses
before
cursor parameter to fetch transactions in reverse chronological order (newest first) - Batch size: Fetches 100 transactions per request
- Continuous polling: The
poll_galoy_transactions
job runs periodically to import new transactions - Unpaired transaction re-checking: Separately polls for older unpaired transactions that may have been missed
Transaction identification:
- Dealer account detection: Identifies transactions involving the hardcoded "dealer" ledger account
- USD conversion tracking: Monitors when users deposit Bitcoin but want to hold USD value
- Settlement currency: Tracks both BTC and USD settlement amounts with exchange rates
Purpose: Connects to OKX exchange to execute the core hedging strategy through Bitcoin perpetual swap contracts.
Role in hedging:
- Perpetual swaps: Shorts BTC-USD-SWAP contracts to hedge Bitcoin price exposure
- Position management: Maintains short positions equivalent to user USD liability
- Account balancing: Manages transfers between funding and trading accounts
- Price data: Fetches real-time BTC prices for hedging calculations
Purpose: Handles Bitcoin on-chain transactions and custody operations for the stablesats system.
How it works for stablesats:
- Funding adjustments: Stablesats maintains Bitcoin in two locations - its own custody (managed by Bria) and on the OKX exchange for trading. When the OKX trading account runs low on Bitcoin capital needed for hedging operations, stablesats uses Bria to send Bitcoin on-chain from its custody to OKX deposit addresses. Conversely, when excess Bitcoin accumulates on OKX, it can be withdrawn back to stablesats custody via Bria to optimize capital allocation
- Withdrawal operations: Uses Bria to withdraw Bitcoin from stablesats custody to OKX exchange when more trading capital is needed
- User deposits Bitcoin → Galoy-client detects transaction involving dealer account
- Calculate hedge requirement → System determines how much USD exposure needs hedging
- Execute hedge → OKX-client shorts equivalent BTC perpetual swaps
- Manage funding → Bria-client transfers Bitcoin between custody and OKX as needed
- Continuous rebalancing → All three clients work together to maintain proper hedge ratios
This creates a complete system where users can hold stable USD value while the system manages Bitcoin price volatility through derivatives hedging and proper capital management.
The stablesats command line interface (CLI) is an application that allows users to get price quotes, and runs configured processes. To view the CLI commands and options, run
$ stablesats
To run the configured processes:
- Make a copy of the stablesats configuration file and rename the file. Ensure that this new configuration is not committed (add to global
.gitignore
) if contributing to the project. - Uncomment the file and update the
galoy.api
andgaloy.phone_number
config values with values contained here. Change theokex.simulated
value totrue
. - Run the CLI
$ stablesats -c $NEW_CONFIGURATION_FILE run
- For help on the
run
command
$ stablesats run --help
To get price quotes:
- Open a new terminal
- Request a quote for given price
$ stablesats price 10000
- For help on the
price
command
$ stablesats price --help