Skip to main content
The Chainrails Paymaster enables you to sponsor protocol fees on behalf of your users, creating a seamless and frictionless payment experience for your application.

​
What is a Paymaster?

Each cross-chain transaction on Chainrails incurs protocol fees to cover costs associated with bridges and relayers. These fees are charged in the token being transferred, eliminating the need for users to hold multiple tokens for gas or fees. With a Paymaster, you can:
  • Cover protocol fees on behalf of your users
  • Remove payment friction and improve conversion rates
  • Control your transaction costs with flexible billing options
Without a Paymaster, your users will pay the protocol fees directly when making cross-chain transfers.

​
Getting Started

​
Step 1: Access the Dashboard

Navigate to the Chainrails Dashboard and go to the Billing section.

​
Step 2: Choose Your Billing Plan

Chainrails offers three billing options to suit different use cases:
Best for: Testing and low-volume applications
  • Users pay their own protocol fees
  • No additional costs to you
  • Easy to get started
  • Upgrade anytime as you scale

​
Step 3: Enable the Paymaster

Once you select either PAYG or Monthly Subscription, the Paymaster is automatically enabled for your account. All transactions using your API key will have protocol fees covered.

​
Using the Paymaster in Your Application

Once enabled, the Paymaster works automatically—no code changes required. Simply make transactions as usual: 
import { chains, tokens, PaymentModal, usePaymentModal } from "@chainrails-sdk/react"

function App() {
  const cr = usePaymentModal({
    to: "0x4F41BCf288E718A36c1e6919c2Dfc2E07d51c675",
    amount: "1000000", // 1 USDC
    chain: chains.BASE,
    token: tokens.USDC,
  })

  return <PaymentModal config={config} {...cr} />
}
PS: Ignore the fees field as that is returned to track usage, but you would notice the totalAmount field would be the same as the amount you are sending.

​
Managing Your Paymaster

​
For PAYG Plans

Funding Your Balance:
  1. Go to the Dashboard → Billing section
  2. Click “Add Funds” to deposit funds to your paymaster balance
  3. Choose your funding amount
Monitoring Usage:
  • View real-time balance in the Dashboard
  • Track transaction history and fee breakdowns
  • Set up low-balance alerts (coming soon)
We recommend maintaining a balance that covers at least 7 days of expected transaction volume.

​
For Monthly Subscription Plans

Transaction Quotas:
  • Your plan includes a set number of transactions per month
  • View your current usage and remaining quota in the Dashboard
  • Overages are automatically charged at the end of your billing cycle
No Manual Management:
  • Transactions never fail due to insufficient balance
  • Automatic renewal each month
  • Upgrade or downgrade anytime

​
Switching Plans

You can change your billing plan at any time from the Dashboard:
  1. Navigate to Billing → Change Plan
  2. Select your new plan
  3. Confirm the change
Plan changes take effect immediately for all new transactions. Any existing in-flight transactions will use your previous plan settings.

​
Best Practices

  • Building consumer-facing dApps where UX is critical
  • Running promotions or subsidizing early user transactions
  • Enterprise applications requiring predictable fee structures
  • Start with PAYG to understand your usage patterns
  • Switch to Monthly Subscription when volume becomes predictable
  • Monitor transaction patterns in the Dashboard
  • Enable low-balance notifications for PAYG plans (coming soon)
  • Review monthly usage reports
  • Track fee trends over time

​
FAQ

Transactions will fail if your paymaster balance is insufficient. Users will see an error and the transaction won’t be processed. To avoid this, regularly monitor your balance and top up as needed.
Yes, you can switch back to the Free plan at any time. This will require users to pay their own protocol fees for subsequent transactions.
Protocol fees vary based on the source and destination chains, token being transferred, and current network conditions. View detailed fee breakdowns for each transaction in your Dashboard.