Title: Daimo Pay LLM Guide
Audience: coding assistants helping devs integrate Daimo Pay
Last updated: 2025-09-03

GOAL
Help the developer embed Daimo Pay to accept deposits or make contract calls in seconds.

STYLE FOR ANSWERS
• Prefer TypeScript with React. Minimal runnable snippets.
• Use @daimo/pay with wagmi, viem, and @tanstack/react-query.
• Show only documented props. Do not invent props or networks.
• If unsure, say you are unsure and point to LINKS at the end.

REQUIRED PACKAGES AND VERSIONS
npm install @daimo/pay wagmi viem@^2.22.0 @tanstack/react-query
Note: viem 2.22.0 or newer is required to cover Daimo supported chains.

CORE CONCEPTS
Intent address: smart contract address that encodes the action. Send any supported asset to it and the action completes on the destination chain.
Settlement: where funds arrive. Users may pay from other networks or apps. Daimo settles to the network and token you specify.
Liquidity provider: accelerates completion but never custodies payer funds. If no provider appears, payer or receiver can finalize permissionlessly.
Refunds: go to refundAddress or the connected wallet depending on the flow.

GLOSSARY
Checkout = fixed amount
Deposit = user chooses amount
Add Money = Deposit
Destination token = token received at settlement
toUnits = exact decimal amount to receive at destination
Native token = zero address 0x0000000000000000000000000000000000000000

HARD RULES AND GOTCHAS
• refundAddress is required and must be valid on all supported networks.
• toUnits must be a precise decimal string. Too many decimals will error.
• If toAddress is a contract it must be whitelisted with Daimo before calls.
• If toCallData is set and toToken is an ERC20 the SDK auto approves toUnits to toAddress just before the call.
• Props on DaimoPayButton are frozen after first render. Use useDaimoPayUI().resetPayment to change them.
• Prefer constants from @daimo/pay-common to avoid mismatched chain and token.

QUICKSTART MINIMAL
providers.tsx
'use client'
import { DaimoPayProvider, getDefaultConfig } from '@daimo/pay'
import { WagmiProvider, createConfig } from 'wagmi'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
const wagmi = createConfig(getDefaultConfig({ appName: 'Daimo Pay Demo' }))
const qc = new QueryClient()
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={wagmi}>
      <QueryClientProvider client={qc}>
        <DaimoPayProvider>{children}</DaimoPayProvider>
      </QueryClientProvider>
    </WagmiProvider>
  )
}

DEPOSIT EXAMPLE
page.tsx
'use client'
import { DaimoPayButton } from '@daimo/pay'
import { optimismUSDC } from '@daimo/pay-common'
import { getAddress } from 'viem'
export default function Page() {
  return (
    <DaimoPayButton
      appId="pay-demo"
      intent="Deposit"
      refundAddress="0xYOUR_REFUND_ALL_NETWORKS"
      toAddress="0xYOUR_TREASURY"
      toChain={optimismUSDC.chainId}
      toToken={getAddress(optimismUSDC.token)}
      onPaymentStarted={console.log}
      onPaymentCompleted={console.log}
    />
  )
}

CHECKOUT EXAMPLE
Use toUnits to fix the amount
toUnits="1.00"    // receive exactly 1.00 units of the destination token

CONTRACT CALL EXAMPLE
Add toCallData and whitelist the contract with Daimo before use

IMPORTANT PROPS REFERENCE
appId string required. Use pay-demo for prototyping only
intent string visual only. Examples: Pay, Deposit, Add Money
toAddress string required. Destination account or contract to call
toChain number required. EVM chain id for destination
toToken string required. ERC20 address or zero address for native token
toUnits string optional. Exact amount to receive. If omitted user enters amount
toCallData string optional. Calldata for a contract call on destination
refundAddress string required. Fallback refund address valid on all supported networks
paymentOptions string[] optional. Allowed extra sources. Options: AllExchanges, Coinbase, Binance, Lemon, AllPaymentApps desktop only, Venmo, CashApp, MercadoPago, Revolut, Wise, Zelle
preferredChains number[] optional. Sort hint
preferredTokens {chain:number,address:string}[] optional. Takes precedence over preferredChains
redirectReturnUrl string optional. Return url after exchange or payment app flows
defaultOpen boolean optional. Open modal on first render
closeOnSuccess boolean optional. Close modal after success
resetOnSuccess boolean optional. Reset modal after success to allow another payment

DYNAMIC UPDATES
Props are frozen after mount. Call useDaimoPayUI().resetPayment({ toUnits, toToken, toChain, toAddress, ... }) to apply changes. Omitted fields keep previous values.

REFUNDS AND BOUNCED PAYMENTS
Destination call revert or failure triggers an automatic refund to refundAddress or to the connected wallet. Overpayment duplicate payment and expired intent also refund remaining funds.

WEBHOOKS OVERVIEW
payment_started when source transaction is seen
payment_completed when destination transfer or call confirms
payment_bounced when destination call reverts and funds are refunded
payment_refunded when a refund is sent
Authenticate incoming webhooks with Authorization: Basic <token> that you got at webhook creation

WORLD AND MINIPAY NOTES
WorldPayButton allows cross chain calls funded by the World Wallet inside a World Mini App
MiniPay deposit flows should set options={{ disableMobileInjector: true }} on DaimoPayProvider and can set connectedWalletOnly on the button to focus on MiniPay balance

COMMON TROUBLESHOOTING
Modal does not update after user changes amount
→ use resetPayment as described above
Refund went to an exchange deposit address
→ set a self controlled refundAddress. Never rely on exchange deposit addresses
MiniPay deposit conflicts with injected wallet
→ set disableMobileInjector on DaimoPayProvider and consider connectedWalletOnly on the button
Contract call fails
→ ensure contract is whitelisted and calldata is correct. Approvals are auto handled when toToken is ERC20 and toCallData is set

SUPPORTED NETWORKS SUMMARY
Settlement to major EVM networks such as Arbitrum Base BSC Celo Ethereum not recommended for settlement due to fees and finality Linea Optimism Polygon Scroll World
Incoming payments also supported from major assets on Solana and USDT on Tron

LINKS
Quickstart https://paydocs.daimo.com/quickstart
SDK Reference https://paydocs.daimo.com/sdk
How It Works https://paydocs.daimo.com/how-it-works
Webhooks https://paydocs.daimo.com/webhooks
Payments API https://paydocs.daimo.com/payments-api
Supported networks https://paydocs.daimo.com/networks
Contact founders@daimo.com