# Daimo Pay Documentation

Daimo Pay lets you accept crypto from any chain, coin, or wallet instantly. Maximize conversion with a call-to-action that is:

- **Intuitive**: Let your customers use any token on any chain
- **Fast**: Payments complete in seconds
- **Simple**: Pay in a single step from any wallet
- **Secure**: No extra counterparties. Daimo never holds user funds.

Developers can onboard users regardless of their coin or chain. Merchants can receive payments in their preferred token or directly to USD in their bank account.

## Quickstart

This guide will get you set up and ready to use Daimo Pay within minutes. Learn how to add `<DaimoPayButton />` to any React app. This is the recommended flow for the best user experience.

Note: You can prototype using `pay-demo` as both the API key and App ID. For production use, you'll need a real API key and App ID.

### Install

Start by installing `@daimo/pay` and its peer dependencies:

```bash
npm install @daimo/pay wagmi viem@^2.22.0 @tanstack/react-query
```

- Wagmi is a React Hooks library for Ethereum
- Viem is a TypeScript interface for Ethereum that performs blockchain operations
- TanStack Query is an async state manager that handles requests, caching, and more

### Basic Integration

```tsx
import { DaimoPayButton } from '@daimo/pay'
import { getAddress } from 'viem'

export function PaymentButton() {
  const optimismUSDC = {
    chainId: 10,
    token: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85'
  }

  return (
    <DaimoPayButton
      appId="pay-demo" // Example app ID for prototyping
      toChain={optimismUSDC.chainId}
      toUnits="1.00" // $1.00 USDC
      toToken={getAddress(optimismUSDC.token)}
      toAddress="PAYMENT_RECIPIENT_ADDRESS_HERE"
      onPaymentStarted={(e) => console.log(e)}
      onPaymentCompleted={(e) => console.log(e)}
    />
  )
}
```

## How It Works

The purpose of Daimo Pay is to offer the best, highest-converting way to pay or deposit crypto.

### Design Goals

- **Any coin, any chain**: If Alice has enough crypto anywhere, she should be able to pay or use your dapp in one click. Swapping and bridging is entirely abstracted.
- **One click**: Only one wallet pop-up to transfer funds. This feels smoother than the typical approve-then-send double popup, and works with CEX transfers directly.
- **Max speed**: Payments should feel immediate. As soon as Alice's payment lands, a liquidity provider completes the transaction on the destination chain, typically two seconds or less.
- **Trustless**: The system is designed without need for trusted custodians.
- **Gasless** (Coming Soon): Support paying even without gas funds on source chain, with a single permit signature.

### Intent Addresses

An intent address is a smart contract that serves as a receiving address: it accomplishes a specific goal just by sending assets to it. Using Ethereum's `CREATE2`, we can make one address that works on all EVM chains. Daimo Pay encodes all the parameters of the action, including amount, destination chain, and contract calls, into the intent address.

### Bridging

Daimo aggregates over multiple bridging protocols:

- CCTP: Used for USDC bridging on CCTP-supported chains
- Across/Axelar: Used for non-CCTP chains

Neither Daimo nor LPs ever control user funds. The contract only allows the exact flow illustrated: from the moment Alice sends funds to the intent address, those funds are guaranteed to end up with Bob.

### Swapping

The intent commits to the exact amount to bridge and the exact amount of the destination transfer. This protects the payer, vendor, and the LP. By swapping to a non-volatile token such as USDC (on the source chain) and completing immediately (on the destination chain), the LP avoids price risk during the time it takes to bridge.

## SDK Reference

The `@daimo/pay` SDK provides React components for integrating payments. Here's the complete reference for the DaimoPayButton component:

### Required Props

- `appId` (string): Your public app ID. Use `pay-demo` for prototyping only.
- `toAddress` (string): The destination address to transfer to, or contract to call.
- `toChain` (number): Destination chain ID.
- `toToken` (string): The destination token address.

### Optional Props

- `intent` (string): The intent verb, such as "Pay", "Deposit", or "Purchase".
- `toUnits` (string): Controls the exact amount to receive (e.g. "1.00" for $1.00 USDC).
- `toCallData` (string): Optional calldata for contract calls.
- `paymentOptions` (string[]): Filter payment options (Coinbase, Binance, Solana, RampNetwork, ExternalChains).
- `preferredChains` (number[]): Optional preferred chain IDs.
- `preferredTokens` (object[]): Optional preferred tokens.
- `externalId` (string): Associates payment with external ID.
- `metadata` (object): Attach key-value data to payment.
- `redirectReturnUrl` (string): Redirect URL after payment.

### Event Handlers

- `onPaymentStarted`: Triggered when payment begins
- `onPaymentCompleted`: Triggered on successful completion
- `onPaymentBounced`: Triggered if payment fails

### Supported Chains

- Arbitrum (42161)
- Base (8453)
- Blast (81457)
- Binance Smart Chain (56)
- Ethereum L1 (1)
- Linea (59144)
- Optimism (10)
- Polygon PoS (137)
- Worldchain (480)

## Payment Links

Payment links are the simplest way for customers to complete on-chain actions with their crypto. They support:

1. **Accept crypto payment**
   - Receive payments in your preferred token/chain
   - Customers pay with any token on any chain
   - Automatic bridging and swapping

2. **Cross-chain bridge and swap with contract call**
   - Enable cross-chain support without contract changes
   - Split payments between multiple recipients
   - Allow NFT purchases with any token
   - Enable complex dapp actions

## Webhooks

Receive real-time notifications when payment status updates occur.

### Event Types

1. **Payment Started**
   - Triggered when user initiates payment
   - Contains source transaction details

2. **Payment Completed**
   - Triggered when payment completes on destination chain
   - Contains final transaction details

3. **Payment Bounced**
   - Triggered if there's an error in destination transaction
   - Funds are refunded to specified address

### Security

- Token-based authentication for webhook verification
- Webhook requests include `Authorization: Basic <token>` header
- Retry mechanism with exponential backoff for failed deliveries

## API Reference

### Create Payment

```bash
POST https://pay.daimo.com/api/payment
```

Required parameters:
- `display`: Payment page settings
- `destination`: Payment recipient details
- API key in headers

### Retrieve Payment

```bash
GET https://pay.daimo.com/api/payment/{id}
```

Returns full payment object with status and transaction details.

## Mini Apps Integration

### Farcaster Mini Apps

The `@daimo/pay` SDK supports integration with Farcaster Mini Apps. Users can make payments directly from a mini app using their Farcaster wallet. No custom integration required - simply include the `DaimoPayButton`.

### World and Opera Mini Apps

Coming soon.

## Getting Help

For support or questions, contact us at founders@daimo.com.

For complete API reference and examples, visit https://paydocs.daimo.com