Daimo Pay SDK

The best way to embed Daimo Pay into your app is via the @daimo/pay SDK.

The SDK is open source. You can find it on NPM and GitHub. For installation instructions, see the Quickstart. For a live demo of common use-cases, see the DaimoPayButton Demo. For details, see below.

DaimoPayButton Reference

Name
appId*
Type
string
Description
Your public app ID. Use pay-demo for prototyping only.
Name
intent
Type
string
Description
The intent verb, such as "Pay", "Deposit", or "Purchase".
Name
toAddress*
Type
string
Description
The destination address to transfer to, or contract to call.
Name
toChain*
Type
number
Description
Destination chain ID.
Name
toUnits*
Type
string
Description
The amount of destination token to send (transfer or approve), as a precise decimal string. For example, "1.00" means $1 USDC. Providing more decimals than the underlying token will result in an error. For computed dollar amounts, we recommend using .toFixed(2).
Name
toToken*
Type
string
Description
The destination token to send, completing payment. Must be an ERC-20 token or the zero address 0x0000000000000000000000000000000000000000, indicating the native token such as ETH. For ERC-20, if toCallData is specified, then the payment amount will be approved to the destination toAddress immediately before calling the contract. Otherwise, the amount will be transferred to toAddress.
Name
amountEditable
Type
boolean
Description
Let the user edit the amount to send.
Name
toCallData
Type
string
Description
Optional calldata to call an arbitrary function on toAddress.
Name
paymentOptions
Type
string[]
Description
Optional filter to show only a subset of payment options. By default, all are enabled. Currently available payment options are Coinbase, Binance, and RampNetwork. With these options, even users with no crypto wallet can complete payment.
Name
preferredChains
Type
number[]
Description
Optional preferred chain IDs. Assets on these chains will appear first.
Name
preferredTokens
Type
object[]
Description
Optional preferred tokens. Assets in these specific tokens will appear first, taking precedence over preferredChains. Each token has the format: { chain: number, address: string }.

  <DaimoPayButton
    {/* Required props */}
    appId="pay-demo"
    toAddress="0x1234567890123456789012345678901234567890"
    toChain={10} // Optimism
    toUnits="1.00" // $1, Optimism USDC
    toToken="0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"

    {/* Optional props */}
    intent="Purchase NFT"
    toCallData="0x1234abcd" // Example contract call data
    paymentOptions={["Coinbase", "Binance"]}
    preferredChains={[10, 8453]} // prefer Optimism, Base
    preferredTokens={[ // prefer Optimism USDC
      { chain: 10, address: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" }
    ]}

    {/* Event handlers */}
    onPaymentStarted={(e) => console.log(e)}
    onPaymentCompleted={(e) => console.log(e)}
    onPaymentBounced={(e) => console.log(e)}
  />

Themes and Customization

You can customize the appearance of both the button and the modal according to preset themes or using customTheme.

Name
mode
Type
string
Description
Light mode, dark mode, or auto.
Name
theme
Type
string
Description
Named theme. See docs for options.
Name
customTheme
Type
object
Description
Custom theme. See docs for options.
Name
closeOnSuccess
Type
boolean
Description
Automatically close the modal after a successful payment.
Name
disabled
Type
boolean
Description
Disable interaction.

  <DaimoPayButton
    appId="pay-demo"
    toAddress="0x1234567890123456789012345678901234567890"
    toChain={8453} // Base
    toUnits="0.001" // 0.001 ETH
    toToken="0x0000000000000000000000000000000000000000"
    
    mode="dark"
    theme="rounded"
    {/* alternatively, customTheme={...} */}

    closeOnSuccess
  />

Event Handlers

Name
onPaymentStarted
Type
function
Description
Called when the user sends payment and the transaction is seen on the chain.
Name
onPaymentCompleted
Type
function
Description
Called when the destination transfer or call completes successfully.
Name
onPaymentBounced
Type
function
Description
Called when the destination call reverts and funds are refunded.

The events passed to the onPayment... handlers match the events passed to webhooks. You can use them for immediate feedback, while using webhooks for things like backend order status tracking. This ensures robust tracking even if the user loses network during payment.

  const [latest, setLatest] = useState<DaimoPayEvent>();

  return (<>
    <DaimoPayButton
      {/* For existing payments created via API, use payId. */}
      payId="72hebvwpDJDA9qNubzb2jYjAbdDgjH4uD53rBnh8BR3A"

      {/* Either way, the onPayment... handlers always work. */}
      onPaymentStarted={setLatest}
      onPaymentCompleted={setLatest}
      onPaymentBounced={setLatest}
    />
    {latest.type === 'payment_started' && <Spinner />}
    {latest.type === 'payment_completed' && <SuccessLink txHash={latest.txHash} />}
    {latest.type === 'payment_bounced' && <RevertLink txHash={latest.txHash} />}
  </>);

DaimoPayButton.Custom

In addition, you can replace the DaimoPayButton entirely with your own button using DaimoPayButton.Custom.

Name
children*
Type
function
Description
Custom renderer function that receives show/hide methods and returns React node.

<DaimoPayButton.Custom
  appId="pay-demo"
  toAddress="0x1234567890123456789012345678901234567890"
  toChain={10} /* Optimism */
  toUnits="1.23" /* $1.23 USDC */
  toToken="0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
>
  {({ show, hide }) => <button onClick={show}>Custom Pay Button</button>}
</DaimoPayButton.Custom>