Skip to content

Fund an app or agent to send messages with XMTP

Use this guide to learn how to use the XMTP Funding Portal to fund an app or agent to send messages with XMTP. You can also use the portal to view usage and current and projected fees.

Behind the scenes, the Funding Portal handles Payer Registry smart contract deposits, XMTP Broadcast Network messaging fee and XMTP App Chain gas payments, and all blockchain interactions.

Ephemera currently hosts the XMTP Funding Portal UI as a community service. Stewardship will move to DUNA post-GA.

The smart contracts used by the portal are fully decentralized and non-custodial. Full audits from Trail of Bits and Octane will be published before paid messaging is enforced.

Understand payer wallets

A payer wallet is what an app or agent's XMTP Gateway Service uses to pay fees.

You can:

For example, you might self-fund your payer wallet if it already has or can easily obtain USDC. Or, you might ask your finance team to fund your payer wallet from a company multi-sig. You might also use a wallet you control to support a different app or agent by funding its payer wallet.

Access the XMTP Funding Portal

At this time, you can access the testnet-staging deployment of the XMTP Funding Portal: https://funding-portal-testnet-staging.vercel.app/.

Use this testnet-staging deployment to test fund and withdrawal flows using a mock token called mxUSD (mock XMTP USD fee token).

To learn how to get mxUSD, see Self-mint mxUSD.

Currently, mxUSD balances on testnet-staging are unaffected by usage.

Self-fund a payer wallet

Step 1. Create the payer wallet

The payer wallet must be:

  • A standard Ethereum-compatible wallet account
  • Non-custodial, meaning you control the private key (not a third-party service)
  • Able to sign and transact on the Base and XMTP App Chain networks
  • Able to hold and transfer USDC tokens

You can create a payer wallet using common non-custodial wallet apps, such as Coinbase Wallet and MetaMask.

Payer wallets can be funded by Ethereum EOAs and smart contract wallets. For example, a Gnosis Safe or any ERC-1271 wallet can deposit funds into a payer account using the Funding Portal.

You'll need your payer wallet's private key when setting up your XMTP Gateway Service.

Step 2. Register the payer wallet

  1. Use your payer wallet to connect to the XMTP Funding Portal.
  2. On the Welcome page, click Use connected wallet.
  3. Open the drop-down menu in the upper right and click Manage payers.
  4. Click the pencil icon to give your payer wallet a human-readable name.
  5. Click the green check button to save.

Your payer wallet is now a payer in the Payer Registry smart contract.

Step 3: Fund the payer wallet with USDC on Base

Fund your payer wallet with USDC on Base. Here are some sources you can use to acquire USDC:

  • Centralized exchanges: Binance, Coinbase, Kraken
  • Direct purchase: Circle, Coinbase
  • Business accounts: Circle business accounts for larger operations

Step 4: Allocate funds for messaging

  1. Connect the payer wallet to the XMTP Funding Portal.
  2. In the drop-down menu in the upper right, be sure to select the payer wallet.
  3. On the Dashboard page, click Fund.
  4. Enter the amount you want to allocate from your payer wallet.
  5. The XMTP Funding Portal automatically optimizes how the funds are allocated to cover messaging fees and gas fees. Expand the Transaction details area to view the details of the split.
  6. Click Continue.
  7. The Depositing funds screen displays. You can click Cancel transaction to attempt to cancel the transaction, if needed.

Your payer wallet now has:

  • An allocation to your registered payer wallet in the Payer Registry smart contract. This allowance will be used to pay XMTP Broadcast Network messaging fees.
  • An amount bridged to your payer wallet on the XMTP App Chain. This balance will be used to pay XMTP App Chain gas fees.

Step 5: Monitor your usage and allowance

You can use the Usage panel on the XMTP Funding Portal Dashboard to review the number of messages sent by your app, as well as actual and projected fees.

Before data can display in the Usage panel, you must have completed the following on the appropriate network (testnet or mainnet):

  1. Deployed your XMTP Gateway Service
  2. Updated your app to use a compatible XMTP SDK
  3. Sent messages using your app

We recommend funding an allowance for 3-6 months of estimated usage.

If your allowance goes to zero, the Payer Registry smart contract rejects new messages sent to the XMTP Broadcast Network and returns an INSUFFICIENT_PAYER_BALANCE error.

Step 6: Withdraw and claim funds

You can use the payer wallet (and only the payer wallet) to withdraw from the messaging and gas fee allowance at any time.

  • Withdrawals from the Payer Registry will be available after 48 hours and require a second transaction to claim.
  • Withdrawals from the XMTP App Chain that require bridging to Base will be available after 7 days and require a second transaction to claim.
  1. Connect your payer wallet to the XMTP Funding Portal.
  2. On the Dashboard page, click Withdraw.
  3. Enter the amount you want to withdraw from your messaging balance. Click MAX if you want to withdraw the maximum amount available.
  4. Click Request withdrawal.
  5. After the required wait time, return to the XMTP Funding Portal to complete your withdrawal. On the homepage, view the Transaction panel and locate your Withdrawal and Bridge transactions. The Status column should be set to Ready to withdraw.
  6. Click Ready to withdraw to display the Transaction details panel.
  7. Verify the withdrawal details and click Claim USDC.

Fund a payer wallet using another wallet

Step 1. Get the payer wallet address

To fund an app using a wallet other than its payer wallet, you need the payer wallet address.

Step 2. Select the payer wallet you want to fund

  1. Use the wallet you want to use to fund the payer wallet to connect to the XMTP Funding Portal.
  2. On the Welcome page, click Use other wallet.
  3. On the Manage payer wallets screen, enter the payer wallet address you want to fund and a human-readable display name.
  4. Click the green check button to save.

Your wallet can now fund the payer wallet.

Step 3: Deposit USDC into your wallet

Deposit USDC into your wallet on Base. This is the wallet you want to use to fund the payer wallet.

Here are some sources you can use to acquire USDC:

  • Centralized exchanges: Binance, Coinbase, Kraken
  • Direct purchase: Circle, Coinbase
  • Business accounts: Circle business accounts for larger operations

Step 4: Allocate funds to the payer wallet

  1. Use the wallet you funded in Step 3 to connect to the XMTP Funding Portal.
  2. In the drop-down menu in the upper right, be sure to select the payer wallet.
  3. On the Dashboard page, click Fund.
  4. Enter the amount you want to allocate from your wallet to the payer wallet.
  5. The XMTP Funding Portal automatically optimizes how the funds are allocated to cover messaging fees and gas fees. Expand the Transaction details area to view the details of the split.
  6. Click Continue.
  7. The Depositing funds screen displays. You can click Cancel transaction to attempt to cancel the transaction, if needed.

The payer wallet now has:

  • An allocation to the registered payer wallet in the Payer Registry smart contract. This allowance will be used to pay XMTP Broadcast Network messaging fees.
  • An amount bridged to the payer wallet on the XMTP App Chain. This balance will be used to pay XMTP App Chain gas fees.

For use with testnet-staging only: Self-mint mxUSD

To fund your app on the testnet-staging deployment of the XMTP Funding Portal, you must use mxUSD (mock XMTP USD fee token) instead of USDC.

To get mxUSD, you must self-mint it.

Self-mint mxUSD

  1. Start Docker Desktop.

  2. Use the xmtpd-cli Docker image with your relevant parameter values to self-mint mxUSD:

     docker run --rm ghcr.io/xmtp/xmtpd-cli:main \
   funds mint --amount <1000> --to <receiving-address>
   --private-key <private-key> \
   --app-rpc-url https://xmtp-ropsten.g.alchemy.com/v2/<your-alchemy-api-key> \
   --settlement-rpc-url https://base-sepolia.g.alchemy.com/v2/<your-alchemy-api-key> \
   --config-file https://github.com/xmtp/smart-contracts/releases/download/v0.5.5/testnet.json \

Available parameters:

  • --amount: Amount of mxUSD to mint, in whole units. For example, 1000.
  • --to: Receiving address (typically your payer wallet address)
  • --private-key: Private key of the address you want to use to pay the gas fee to mint the mxUSD
  • --app-rpc-url: Your Alchemy API endpoint for XMTP Ropsten
  • --settlement-rpc-url: Your Alchemy API endpoint for the Base Sepolia

To learn how to create an Alchemy API endpoint, see Create an Alchemy API Key.

Expected output:

INFO    funds-admin     tokens minted   {"settlement_chain_id": 84532, "app_chain_id": 351243127, "from_address": "0x0000000000000000000000000000000000000000", "to": "0x132455a4306D362d7D051B7c2f2c96d9021D6a1c", "amount": "1000000000"}
INFO    successfully minted mock underlying fee token   {"to": "0x132455a4306D362d7D051B7c2f2c96d9021D6a1c", "amount": "1000000000"}

Note that the amount in the output is shown in the smallest unit with 6 decimal places, so 1000000000 equals 1000 mxUSD.

Add mxUSD to MetaMask

After self-minting mxUSD, you'll need to add the token to MetaMask to view your balance:

  1. Open MetaMask and select the Tokens tab.
  2. Open the kebab menu and click Import tokens.
  3. Select the Base Sepolia network and enter these token details:
    • Token contract address: 0x2d7e0534183dAD09008C97f230d9F4f6425eE859
    • Token symbol: mxUSD
    • Token decimal: 6
  4. Click Next.
  5. Click Import to confirm.

Your mxUSD balance should now be visible in MetaMask.

Troubleshooting

Is there a testnet?

Yes. There are testnets for the XMTP App Chain and XMTP Broadcast Network.

At this time, you can dry-run allocating funds using the testnet-staging deployment of the XMTP Funding Portal and sending messages using these XMTP testnets.

Signature rejected (MetaMask only)

If you see a Signature rejected error in MetaMask, it can sometimes be caused by a stuck or out-of-sync nonce (a number that keeps track of your transaction order).

To fix this:

  1. Open MetaMask.
  2. Click your account icon in the top right.
  3. Go to Settings → Advanced.
  4. Click Reset Account. This does not affect your funds or wallet.

If the issue persists:

  • Check for any stuck or pending transactions in your wallet.
  • Try sending a new transaction with a custom nonce if needed.

Bridge pending > 15 min

Check Base status: https://status.base.org/.

Message reverted

Check for INSUFFICIENT_PAYER_BALANCE.

Region restrictions

Nodes in the XMTP testnet and mainnet that operate in US jurisdiction do so in compliance with Office of Foreign Assets Control (OFAC) sanctions and Committee on Foreign Investment in the United States (CFIUS) export compliance regulations. Accordingly, for these nodes, IP-based geoblocking is in place for the following countries/territories:

  • Cuba
  • Iran
  • North Korea
  • Syria
  • The Crimea, Donetsk People’s Republic, and Luhansk People’s Republic regions of Ukraine