Chialisp Guide Pt 17: Payments & Invoicing on Chia

Key Takeaways

• Chialisp payments use programmable “smart coins” controlled by puzzles instead of traditional accounts, giving you fine-grained control over when and how funds move.
• The CREATE_COIN condition (opcode 51) is the primary mechanism for creating payment transactions, requiring a puzzle hash (recipient address) and amount in mojos (1 XCH = 1 trillion mojos).
• Chia Offers enable peer-to-peer, non-custodial asset swaps without intermediaries using the settlement payments puzzle to ensure atomic transactions.
• Advanced payment patterns like rate-limited wallets, payment channels, and streaming payments can be implemented through custom Chialisp puzzles.
• Real-world applications include the World Bank’s Climate Warehouse platform, which uses Chia’s blockchain infrastructure for tracking carbon credit metadata and supporting tokenized carbon credit transactions through initiatives like the IFC-backed Carbon Opportunities Fund.

Chialisp payments transform every transaction into a programmable smart coin, allowing developers to build payment systems with embedded logic for subscriptions, escrows, multi-signature approvals, and automated settlements—all without relying on centralized payment processors or requiring both parties to be online simultaneously.

Understanding Chia’s Coin-Based Payment Model

Before diving into payment implementations, it’s crucial to understand that Chia uses a fundamentally different approach from account-based blockchains like Ethereum. In Chia’s Coin Set model, every payment is actually a coin spend where the coin is locked by a Chialisp puzzle that defines the spending conditions.

When you receive a payment on Chia, you’re not increasing an account balance—you’re creating a new coin that’s locked to a puzzle hash you control. This architecture provides several advantages for payment systems. First, it allows parallel transaction processing since coins are independent of each other. Second, it enables more secure smart contracts because each coin’s rules are self-contained and can’t be affected by other transactions. Third, it makes atomic multi-party transactions simpler to implement since all coins in a transaction are spent simultaneously.

The coin model also means that payments can carry programmable logic beyond simple value transfer. You can create coins that only unlock under specific conditions, that automatically split payments between multiple recipients, or that enforce spending limits over time. This flexibility is what makes Chialisp particularly powerful for building payment and invoicing systems.

Core Components of a Chia Payment

Every Chia payment consists of three essential elements: the puzzle (Chialisp code defining spending rules), the solution (arguments provided to unlock the puzzle), and conditions (outputs that determine what happens when the coin is spent). Understanding how these components work together is fundamental to building payment systems.

The puzzle is the Chialisp program that locks the coin. For standard wallet payments, this is the Standard Transaction puzzle which validates a signature. For custom payment systems, you can write puzzles that enforce business logic, time locks, multi-signature requirements, or any other rules you need. The puzzle hash—a cryptographic hash of the puzzle—serves as the “address” where payments are sent.

The solution provides the data needed to satisfy the puzzle’s requirements. For a password-locked coin, the solution would be the password. For a signature-locked coin, it includes the signature and sometimes a list of conditions to execute. The puzzle evaluates the solution and, if valid, returns a list of conditions that tell the blockchain what to do.

Mojo Denomination and Amount Calculations

All payment amounts in Chia are calculated in mojos, the smallest indivisible unit of XCH. One XCH equals exactly 1,000,000,000,000 mojos (one trillion). This high precision allows for microtransactions and precise value calculations without rounding errors.

When building payment systems, always work with integer mojos rather than floating-point XCH values to avoid precision loss. For example, a payment of 0.5 XCH should be represented as 500,000,000,000 mojos. This approach ensures your calculations remain accurate even when dealing with very small amounts or complex fee structures.

Quick Decision Table: Choosing Your Payment Implementation

CREATE_COIN: The Foundation of Chialisp Payments

The CREATE_COIN condition (condition code 51) is the primary mechanism for executing payments in Chialisp. When a puzzle returns CREATE_COIN conditions, it instructs the blockchain to create new coins with specified puzzle hashes and amounts. This is how value moves from one address to another on the Chia network.

The CREATE_COIN condition takes three parameters: the puzzle hash (destination address), the amount in mojos, and optional memos for metadata. For example, (51 0x9a3f… 1000000000000) creates a coin worth 1 XCH at the specified puzzle hash. The blockchain validates that the total amount created doesn’t exceed the amount being spent, with the difference going to farmer fees.

Here’s a simple example of creating a payment using CREATE_COIN in Chialisp:

(mod (recipient_puzzle_hash amount)
  ; Create a coin paying to the recipient
  (list (list 51 recipient_puzzle_hash amount))
)

This basic puzzle takes a recipient’s puzzle hash and an amount, then returns a CREATE_COIN condition that sends the specified amount to that address. Real-world payment puzzles build on this foundation by adding validation logic, signature requirements, and complex spending conditions.

Multiple Recipients and Change Handling

Most payment transactions involve creating multiple coins—one or more for recipients and often one for “change” back to the sender. When a coin’s value exceeds the payment amount, the puzzle creates two CREATE_COIN conditions: one for the recipient and one returning the remainder to the sender’s address.

(mod (recipient_puzzle_hash payment_amount sender_puzzle_hash total_amount fee)
  (list
    ; Pay recipient
    (list 51 recipient_puzzle_hash payment_amount)
    ; Return change to sender (total - payment - fee)
    (list 51 sender_puzzle_hash (- (- total_amount payment_amount) fee))
  )
)

The wallet software handles these calculations automatically for standard payments, but understanding the mechanism is essential when building custom payment systems. Each CREATE_COIN condition you return represents a new coin that will exist after the spend completes.

Chia Offers: Decentralized Payment Swaps

Chia Offers provide a powerful mechanism for peer-to-peer asset exchanges without requiring trusted intermediaries or both parties to be online simultaneously. An Offer is essentially a partially-signed transaction that proposes a trade—one party offers certain assets in exchange for others.

The offer creator spends their coins to create “settlement payment” coins locked by a special puzzle. These settlement coins can only be claimed if the taker provides the requested assets in return. The settlement payments puzzle uses announcements to ensure atomicity—either the entire trade completes or none of it does.

How Offers Work for Payments

When you create an offer to sell 10 XCH for 100 USDS tokens, you’re actually creating a spend bundle that:

1. Spends your 10 XCH coins
2. Creates settlement payment coins that announce “I will pay 10 XCH”
3. Asserts that an announcement exists saying “I received 100 USDS”
4. Partially signs this bundle and shares it as an offer file

The taker completes the offer by:

1. Spending their 100 USDS tokens
2. Creating coins paying 100 USDS to your address
3. Making the required announcement that the settlement puzzle needs
4. Claiming the 10 XCH from the settlement coins
5. Adding their signature and broadcasting the complete transaction

This mechanism enables decentralized exchanges, NFT marketplaces, and atomic swaps without custody risk. If the taker doesn’t provide the requested assets, the settlement coins remain locked and the offer simply times out.

Advanced Payment Patterns

Rate-Limited Wallets

Rate-limited wallets implement spending restrictions directly in Chialisp, allowing you to create wallets with built-in allowances. These are particularly useful for departmental budgets, allowances for dependents, or adding security layers to hot wallets.

A rate-limited puzzle tracks how much has been spent over a time period and only allows spending up to a configured limit. The implementation typically works by:

1. Storing the rate limit parameters (amount per period, time interval) in the puzzle
2. Tracking the last withdrawal time and amount
3. Validating each spend against the remaining allowance
4. Creating a new rate-limited coin with updated tracking data

The puzzle verifies that the parent coin has the same puzzle hash to prevent circumvention attacks where someone tries to reset the rate limiting by creating a new coin. This ensures the spending history persists across transactions.

Payment Channels

Payment channels enable high-frequency micropayments between two parties without broadcasting every transaction to the blockchain. This is ideal for use cases like streaming media payments, IoT device settlements, or gaming microtransactions where on-chain fees would be prohibitive.

A payment channel works by:

1. Opening: Both parties fund a multi-signature coin on-chain
2. Transacting: They exchange signed state updates off-chain, each one representing a new balance split
3. Closing: Either party can broadcast the most recent signed state to settle the channel on-chain

The channel can process thousands of micropayments off-chain with only two on-chain transactions (open and close), dramatically reducing costs while maintaining security through the signed state updates.

Streaming Payments (CHIP-0041)

Streaming payments, as proposed in CHIP-0041 (currently in review status), enable continuous payment flows where the recipient’s claimable amount increases proportionally with time. This is particularly useful for subscriptions, salary payments, or vesting schedules.

A streaming payment coin holds the total amount to be transferred over a time period. As time passes, the receiver can claim their accrued portion at any point. The puzzle automatically calculates the claimable amount based on elapsed time and creates a new streaming coin with the remainder when claimed.

The implementation includes a clawback mechanism allowing the sender to stop the stream early, with the receiver retaining all amounts that had already accrued. This provides flexibility for use cases like DAO contributor rewards where funding might need to be halted based on performance or organizational changes.

Building Custom Invoice Systems

Custom invoice puzzles allow businesses to implement automated billing directly on-chain. An invoice puzzle can enforce payment terms, due dates, and even late fees entirely through Chialisp logic.

Basic Invoice Structure

An invoice puzzle typically includes:

• Payee information: The puzzle hash where payment should be sent
• Invoice amount: The required payment in mojos
• Due date: A timestamp after which late fees might apply
• Payment conditions: Any special terms or requirements

(mod (
  PAYEE_PUZZLE_HASH
  INVOICE_AMOUNT
  DUE_DATE
  payment_amount
  payment_time
)
  (if (> payment_time DUE_DATE)
    ; Late payment - add 10% fee
    (if (= payment_amount (* INVOICE_AMOUNT 1.1))
      (list (list 51 PAYEE_PUZZLE_HASH payment_amount))
      (x) ; Reject insufficient late payment
    )
    ; On-time payment
    (if (= payment_amount INVOICE_AMOUNT)
      (list (list 51 PAYEE_PUZZLE_HASH payment_amount))
      (x) ; Reject insufficient payment
    )
  )
)

This example implements a simple late fee structure, but the pattern extends to complex scenarios like partial payments, payment plans, or multi-milestone project invoicing.

Automated Subscription Payments

Subscription services can be implemented by combining invoice puzzles with time-based conditions. The subscriber creates a rate-limited wallet that automatically allows withdrawals up to the subscription amount per billing period.

The service provider can then claim their subscription payment by spending from this wallet whenever a billing period elapses. The rate limit prevents over-charging, while the puzzle structure eliminates the need for the subscriber to manually approve each payment.

Multi-Signature Payment Controls

Multi-signature puzzles require approvals from multiple parties before a payment can execute. This is essential for corporate treasuries, joint accounts, or escrow services where multiple stakeholders need signing authority.

A 2-of-3 multi-sig puzzle might look like:

(mod (
  PUBKEY_1
  PUBKEY_2
  PUBKEY_3
  signature_1
  signature_2
  conditions
)
  ; Verify we have two valid signatures from different keys
  ; then return the payment conditions
  (if (all-signatures-valid signature_1 signature_2)
    conditions
    (x)
  )
)

The actual implementation uses BLS signature aggregation and validation against the provided public keys. Chia’s signature scheme makes this particularly efficient since multiple signatures can be combined into a single aggregated signature.

Integrating Chialisp Payments into Applications

Command-Line Payment Example

For developers building on Chia, the CLI provides direct access to payment functionality:

# Send a basic payment
chia wallet send -a 1.5 -t xch1recipient_address -m 0.0001

# Create an offer trading XCH for CATs
chia wallet make_offer -o 10:xch -r 100:cat_asset_id -p offer.txt

# Take an existing offer
chia wallet take_offer offer.txt

These commands handle the complexity of puzzle construction, signature generation, and transaction broadcasting while giving you programmatic control over payments.

JavaScript/TypeScript Integration

For web and mobile applications, the chia-rpc and clvm-lib libraries enable Chialisp payment integration:

import { FullNode, formatHex } from 'chia-rpc';
import { Program } from 'clvm-lib';

// Connect to node
const node = new FullNode(rpcHost);

// Create payment conditions
const conditions = `(
  (${CREATE_COIN} ${recipientPuzzleHash} ${amountInMojos})
)`;

// Build and submit spend bundle
const solution = Program.fromSource(`(${conditions})`);
const spendBundle = createSpendBundle(coinId, puzzle, solution);

await pushTransaction(spendBundle);

This approach allows web applications, mobile apps, and backend services to create payments without requiring users to interact with command-line tools. The same patterns extend to creating Offers, monitoring payment status, and implementing complex business logic.

Security Considerations for Payment Systems

When building payment systems with Chialisp, security must be a primary concern from the start. The immutability of blockchain transactions means that errors can’t be undone—funds sent to the wrong address or locked by a buggy puzzle are permanently lost. Several critical security practices should guide your development.

First, thoroughly test all puzzles on testnet before deploying with real funds. Create comprehensive test cases that verify not just the happy path but also edge cases, malicious inputs, and failure modes. Use the Chialisp simulator to analyze how puzzles behave under different conditions before committing code to mainnet.

Second, implement proper validation of all inputs to your puzzles. Never trust that solutions will be well-formed or that amounts will be reasonable. Check for integer overflows, validate puzzle hashes are the expected length, and ensure that created coin amounts don’t exceed spent amounts. Each validation adds a small computational cost but prevents potentially catastrophic failures.

Third, consider the attack surface of announcement-based coordination. As noted in CHIP-25, improper use of coin announcements can create security vulnerabilities. Always include coin IDs in announcement messages to prevent replay attacks, and use the newer SEND_MESSAGE and RECEIVE_MESSAGE conditions when possible for stronger security guarantees.

Common Payment Security Pitfalls

Several common mistakes can compromise payment security. Unprotected announcements that omit coin IDs allow attackers to reuse announcements across multiple transactions, potentially enabling theft. Insufficient amount validation can allow attackers to create coins worth more than the spent amount through integer overflow exploits. And exposing private keys or signatures in puzzle solutions makes funds vulnerable to theft by observers.

Another critical issue is memo-based data leakage. While memos can carry useful metadata for payment tracking, they’re publicly visible on the blockchain. Never include sensitive information like customer personally identifiable information, internal system details, or business-sensitive data in memos. Use opaque identifiers that map to private databases for tracking purposes.

Optimizing Payment Performance

Payment system performance impacts both user experience and operational costs. Slow transactions frustrate users, while high costs make micro-payments economically impractical. Optimization focuses on reducing CLVM cost, minimizing blockchain overhead, and batching operations when possible.

CLVM cost is determined by the complexity of puzzle execution. Simpler puzzles cost less and process faster. When designing payment puzzles, favor straightforward logic over clever but complex implementations. Use efficient Chialisp patterns like short-circuit evaluation to avoid unnecessary computation when conditions aren’t met.

For high-volume payment systems, consider batching multiple payments into single transactions. Instead of creating 100 separate transactions for 100 payments, create one transaction that generates 100 coins. This dramatically reduces fees and blockchain space while still providing atomic execution guarantees.

Fee Estimation and Management

Accurate fee estimation ensures payments process quickly without overpaying. The Chia blockchain’s fee market is based on CLVM cost, with higher fees prioritizing transactions during network congestion. Standard wallet transfers with a CLVM cost around 6 million typically require fees ranging from 0.00003 to 0.0001 XCH depending on network conditions, with 0.0001 XCH recommended for faster, more reliable processing. Complex operations like CAT transfers, Offers, or NFT transactions may need 0.001 XCH (1 billion mojos) or more.

Dynamic fee estimation based on current mempool conditions provides the best user experience. Tools like XCH.tools offer real-time fee estimates for various transaction types. Your payment system should monitor the mempool and adjust fees accordingly—using lower fees when the network is quiet and increasing fees during congestion to ensure timely processing.

Conclusion

Chialisp payments represent a fundamental shift in how we think about value transfer on blockchain systems. By treating every payment as a programmable coin controlled by custom logic, Chia enables payment patterns that are impossible on traditional account-based systems. From simple transfers using CREATE_COIN conditions to sophisticated systems involving Offers, payment channels, and streaming payments, the flexibility of Chialisp opens new possibilities for financial applications.

Real-world deployments demonstrate that these aren’t just theoretical capabilities—Chialisp payments are handling actual financial instruments with regulatory compliance and enterprise security requirements. The World Bank’s Climate Warehouse platform uses Chia’s blockchain infrastructure for tracking carbon credit metadata, while the IFC-backed Carbon Opportunities Fund has successfully implemented tokenized carbon credit transactions on Chia’s network. As you build your own payment systems, remember the core principles: leverage the coin model’s inherent properties, implement thorough security validation, and test extensively before mainnet deployment.

Whether you’re creating an invoicing system for your business, building a decentralized exchange, or implementing subscription payments for your service, Chialisp gives you the tools to encode payment logic directly on-chain with strong security guarantees and without trusted intermediaries. The patterns covered in this lesson provide the foundation—now it’s time to build your payment innovations on Chia.

Chialisp Payments FAQs

How do I convert XCH to mojos for Chialisp payments?

To convert XCH to mojos for Chialisp payments, multiply the XCH amount by 1,000,000,000,000 (one trillion). For example, 1.5 XCH equals 1,500,000,000,000 mojos. Always use integer mojos in your code rather than floating-point XCH values to avoid precision errors in payment calculations.

What is the difference between CREATE_COIN and CREATE_PUZZLE_ANNOUNCEMENT in Chialisp payments?

CREATE_COIN (condition 51) actually creates a new coin with a specified puzzle hash and amount, executing the payment transfer. CREATE_PUZZLE_ANNOUNCEMENT creates an announcement message tied to a puzzle hash, which is used for coordinating multi-coin spends in systems like Chia Offers but doesn’t transfer value by itself.

Can Chialisp payments be reversed if sent to the wrong address?

No, Chialisp payments cannot be reversed once confirmed on the blockchain. The immutability of the Chia blockchain means funds sent to a puzzle hash are permanently locked to that puzzle. Always verify recipient addresses before sending payments and implement confirmation steps in user-facing applications.

How do rate-limited wallets prevent spending beyond the set limits in Chialisp?

Rate-limited wallets use Chialisp puzzles that validate each spend against configured time intervals and withdrawal limits. The puzzle checks that the parent coin has the same puzzle hash to prevent duplication attacks, then enforces that withdrawals don’t exceed the allowed amount for the elapsed time period before creating the payment coins.

What makes Chia Offers different from traditional payment escrow services?

Chia Offers enable trustless peer-to-peer payment swaps without requiring escrow services or both parties being online simultaneously. The settlement payments puzzle ensures atomic execution—either both sides of the trade complete or neither does—using on-chain announcements rather than trusted third parties to coordinate the transaction.

Chialisp Payments Citations

1. Chia Network. “Offers | Chialisp.” Chialisp.com. https://chialisp.com/offers/
2. Chia Network. “Conditions | Chialisp.” Chialisp.com. https://chialisp.com/conditions/
3. Chia Network. “First Smart Coin | Chialisp.” Chialisp.com. https://chialisp.com/chialisp-first-smart-coin/
4. Chia Network. “Chialisp and TypeScript | Chia Documentation.” Docs.chia.net. https://docs.chia.net/guides/crash-course/chialisp-and-typescript/
5. Chia Network. “CHIP-0025: Message Conditions.” GitHub. https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0025.md
6. Chia Network. “CHIP-0041: Streaming Payments Puzzle.” GitHub. https://github.com/Chia-Network/chips/blob/59e90f00bb07445c07b6db8832f6cc105f860456/CHIPs/chip-0041.md
7. Chia Network. “Getting to Know the Mempool and Transaction Fees.” Chia.net, January 12, 2024. https://www.chia.net/2024/01/12/getting-to-know-the-mempool-and-transaction-fees/
8. Chia Network. “Finance – Chia Network.” Chia.net. https://www.chia.net/finance/
9. Hoffman, Gene. “From Carbon Market to One Market.” Chia.net, August 28, 2024. https://www.chia.net/2024/08/28/from-carbon-market-to-one-market/
10. Chia Network. “Climate – Chia Network.” Chia.net. https://www.chia.net/climate/
11. Business Wire. “Costa Rica and Chia Announce Partnership to Support Climate and Government Initiatives.” November 11, 2021. https://www.businesswire.com/news/home/20211111005809/en/Costa-Rica-and-Chia-Announce-Partnership-to-Support-Climate-and-Government-Initiatives
12. Cohen, Bram. Twitter post. December 5, 2019. https://x.com/bramcohen/status/1202700142370902016
13. Yahoo Finance. “IFC-Backed Carbon Opportunities Fund Uses Chia Network to Settle Tokenized Carbon Credits.” June 28, 2023. https://finance.yahoo.com/news/ifc-backed-carbon-opportunities-fund-130000097.html
14. Chia Network. “Tokenization: The path toward greater market liquidity.” Chia.net, October 10, 2024. https://www.chia.net/2024/10/10/tokenization-the-path-toward-greater-market-liquidity/
15. Chia Network. “Block Rewards | Chia Documentation.” Docs.chia.net. https://docs.chia.net/chia-blockchain/consensus/block-validation/block-rewards/
16. The Climate Warehouse. “World Bank Climate Warehouse.” Theclimatewarehouse.org. https://www.theclimatewarehouse.org/work/climate-warehouse