PYUSD on Solana: The Practical Integration Guide (with BlockEden.xyz RPC)
PayPal USD (PYUSD) has landed on Solana, marking a significant milestone for digital payments. This guide provides a direct, production-minded walkthrough for engineers integrating PYUSD into wallets, dApps, and commerce platforms on Solana.
All examples use fresh, Token-2022-aware code and are designed to work seamlessly with BlockEden.xyz's low-latency Solana RPC endpoints.
TL;DR
- What: PayPal USD (PYUSD) is now a native Token-2022 SPL token on Solana, offering fast, low-fee settlement for a globally recognized stablecoin.
- Key Params: Mint
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo, decimals6, and token programToken-2022. - Feature Set: Leverages Solana Token Extensions (Token-2022). It has a Transfer Hook initialized but currently inactive (null program), along with confidential transfer capabilities and other extensions.
- Cross-chain: An official LayerZero integration enables PYUSD to move between Ethereum and Solana via a secure burn-and-mint mechanism, bypassing traditional bridges.
- Action: Use this guide as a drop-in template to add PYUSD support to your application with BlockEden.xyz's reliable Solana RPC.
Why PYUSD on Solana Matters
The combination of PayPal's brand with Solana's performance creates a powerful new rail for digital dollars.
- Consumer Trust Meets Crypto UX: PYUSD is issued by the regulated trust company Paxos and is deeply integrated into PayPal and Venmo. This gives users a familiar asset. They can hold a single PYUSD balance and choose to withdraw to an external wallet on either Ethereum or Solana, abstracting away chain complexity.
- Payments-Ready Rails: Solana’s architecture provides sub-second transaction finality and fees that are fractions of a cent. PYUSD layers a stable, recognizable unit of account on top of this efficient settlement network, making it ideal for payments, commerce, and remittances.
- Institution-Grade Controls: By launching as a Token-2022 token, PYUSD can utilize built-in extensions for features like confidential transfers, rich metadata, and a permanent delegate. This enables advanced compliance and functionality without requiring bespoke, difficult-to-audit smart contracts.
The Absolute Essentials (Pin These)
Before you write a single line of code, get these parameters locked in. Always verify the mint address in a trusted explorer to avoid interacting with fraudulent tokens.
- Mint (Mainnet):
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo - Decimals:
6(meaning 1 PYUSD = 1,000,000 base units) - Token Program:
Token-2022(Program ID:TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb) - Token Extensions Used (at mint):
- Metadata & Metadata Pointer
- Permanent Delegate
- Transfer Hook (initialized with a null program)
- Confidential Transfer Configuration
You can verify all of this on the Solana Explorer. The explorer will clearly show the official mint address and its enabled extensions.
Set Up Your Project
Let's get our environment ready. You'll need the latest Solana web3 and SPL token libraries to ensure full Token-2022 compatibility.
1. Libraries
Install the necessary packages from npm.
npm i @solana/web3.js @solana/spl-token
2. RPC Connection
Point your application to your BlockEden.xyz Solana Mainnet RPC URL. For production, environment variables are a must.
// package.json
// npm i @solana/web3.js @solana/spl-token
import { Connection, Keypair, PublicKey } from "@solana/web3.js";
import {
TOKEN_2022_PROGRAM_ID,
getMint,
getOrCreateAssociatedTokenAccount,
getAssociatedTokenAddress,
createTransferCheckedInstruction,
} from "@solana/spl-token";
// Use your BlockEden.xyz Solana RPC URL from your dashboard
const RPC_ENDPOINT =
process.env.SOLANA_RPC_URL ??
"[https://your-blockeden-solana-mainnet-endpoint.com](https://your-blockeden-solana-mainnet-endpoint.com)";
export const connection = new Connection(RPC_ENDPOINT, "confirmed");
// PYUSD (mainnet)
export const PYUSD_MINT = new PublicKey(
"2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
);
Reading PYUSD Mint Data
First, let's programmatically confirm the PYUSD mint's properties. This is a crucial first step to ensure your constants are correct and to fetch details like total supply.
// Confirm PYUSD mint info via Token-2022 APIs
const mintInfo = await getMint(
connection,
PYUSD_MINT,
"confirmed",
TOKEN_2022_PROGRAM_ID, // Specify the program ID
);
console.log({
supply: mintInfo.supply.toString(),
decimals: mintInfo.decimals, // Expect 6
isInitialized: mintInfo.isInitialized,
});
Notice we explicitly pass TOKEN_2022_PROGRAM_ID. This is the most common source of errors when working with Token Extensions.
Create or Fetch Associated Token Accounts (ATAs)
Associated Token Accounts for Token-2022 tokens must be derived using the Token-2022 program ID. If you use the legacy TOKEN_PROGRAM_ID, transactions will fail with an "incorrect program id" error.
// Payer and owner of the new ATA. Replace with your wallet logic.
const owner = Keypair.generate();
// Create or fetch the owner's PYUSD ATA (Token-2022 aware)
const ownerAta = await getOrCreateAssociatedTokenAccount(
connection,
owner, // Payer for creation
PYUSD_MINT, // Mint
owner.publicKey, // Owner of the ATA
false, // allowOwnerOffCurve
"confirmed",
undefined, // options
TOKEN_2022_PROGRAM_ID, // <-- IMPORTANT: Use Token-2022 Program ID
);
console.log("Owner PYUSD ATA:", ownerAta.address.toBase58());
Checking PYUSD Balances
To check a user's PYUSD balance, query their ATA, again remembering to specify the correct program ID.
Using @solana/spl-token
import { getAccount } from "@solana/spl-token";
const accountInfo = await getAccount(
connection,
ownerAta.address,
"confirmed",
TOKEN_2022_PROGRAM_ID,
);
const balance = Number(accountInfo.amount) / 10 ** mintInfo.decimals; // decimals = 6
console.log("PYUSD balance:", balance);
Using Direct JSON-RPC (curl)
You can also check all token accounts for an owner and filter by the Token-2022 program ID.
curl -X POST "$SOLANA_RPC_URL" -H 'content-type: application/json' -d '{
"jsonrpc":"2.0",
"id":1,
"method":"getTokenAccountsByOwner",
"params":[
"<OWNER_PUBLIC_KEY>",
{ "programId":"TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" },
{ "encoding":"jsonParsed" }
]
}'
Transferring PYUSD (User-to-User)
The rule of thumb for transferring any Token-2022 asset is to use createTransferCheckedInstruction. This instruction includes the token's decimals, preventing potential decimal-related vulnerabilities.
Here's a complete, reusable function for transferring PYUSD.
import { Transaction } from '@solana/web3.js';
async function transferPyusd({
fromWallet, // The sender's Keypair
toPubkey, // The recipient's PublicKey
uiAmount, // The amount in PYUSD, e.g., 1.25
}: {
fromWallet: Keypair;
toPubkey: PublicKey;
uiAmount: number;
}) {
const decimals = 6; // From mintInfo.decimals
const rawAmount = BigInt(Math.round(uiAmount * (10 ** decimals)));
// Get the sender's ATA address
const fromAta = await getAssociatedTokenAddress(
PYUSD_MINT,
fromWallet.publicKey,
false,
TOKEN_2022_PROGRAM_ID
);
// Ensure the recipient's ATA exists for Token-2022
const toAta = await getOrCreateAssociatedTokenAccount(
connection,
fromWallet, // Payer
PYUSD_MINT,
toPubkey,
false,
'confirmed',
undefined,
TOKEN_2022_PROGRAM_ID
);
const transferInstruction = createTransferCheckedInstruction(
fromAta, // Source ATA
PYUSD_MINT, // Mint
toAta.address, // Destination ATA
fromWallet.publicKey, // Owner of the source ATA
rawAmount, // Amount in base units
decimals, // Decimals
[], // Multisig signers
TOKEN_2022_PROGRAM_ID // <-- IMPORTANT
);
const transaction = new Transaction().add(transferInstruction);
// Set recent blockhash and fee payer
transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
transaction.feePayer = fromWallet.publicKey;
const signature = await connection.sendTransaction(transaction, [fromWallet]);
await connection.confirmTransaction(signature, 'confirmed');
console.log('Transaction successful with signature:', signature);
return signature;
}
A Note on the Transfer Hook: PYUSD's mint initializes the Transfer Hook extension but sets its program to null. This means standard transfers currently work without extra accounts or logic. If PayPal/Paxos ever activate the hook, they will update the mint to point to a new program. Your integration would then need to pass the extra accounts required by that program's interface.
Solana CLI Quick Test
For a quick manual test from your command line, you can use spl-token with the correct program ID.
# Ensure your CLI points to mainnet and your keypair is funded.
# Transfer 1.00 PYUSD to a recipient.
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
transfer 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo 1.00 <RECIPIENT_PUBKEY> \
--fund-recipient --allow-unfunded-recipient
Cross-Chain PYUSD (Ethereum ↔ Solana)
PayPal has implemented an official cross-chain facility using LayerZero. Instead of relying on risky third-party bridges, this is a native burn-and-mint process: PYUSD is burned on the source chain (e.g., Ethereum) and an equivalent amount is minted on the destination chain (Solana). This eliminates bridge-specific risks and slippage.
You can find the full tutorial and parameters in the official PayPal Developer documentation.
Test with Faucets
For development and testing, do not use mainnet assets. Use the official faucets:
- Paxos PYUSD Faucet: To get testnet PYUSD tokens.
- Solana Faucet: To get devnet/testnet SOL for transaction fees.
Common Pitfalls (And Fixes)
- Wrong Program ID: Problem: Transactions fail with
incorrect program id for instruction. Fix: PassTOKEN_2022_PROGRAM_IDexplicitly to allspl-tokenhelper functions (getOrCreateAssociatedTokenAccount,getAccount,createTransferCheckedInstruction, etc.). - Wrong Mint or Spoofed Assets: Problem: Your application interacts with a fake PYUSD token. Fix: Hardcode and verify the official mint address:
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo. Use an explorer that warns about non-canonical mints. - Decimals Mismatch: Problem: Sending 1 PYUSD actually sends 0.000001 PYUSD. Fix: Always convert UI amounts to raw amounts by multiplying by
10^6. Fetch the mint's decimals programmatically to be safe. - Hook Assumptions: Problem: You pre-build complex logic for a transfer hook that isn't active. Fix: Check the mint's extension data. As of today, PYUSD's hook is null. Build your system to adapt if the hook program is enabled in the future.
Production Checklist for PYUSD + BlockEden.xyz
When moving to production, ensure your infrastructure is robust.
- RPC: Use a high-availability BlockEden.xyz endpoint. Use
confirmedcommitment for responsive UX and query withfinalizedfor operations requiring ledger integrity. - Retry & Idempotency: Wrap transaction submissions with an exponential backoff retry mechanism. Store an idempotency key with each business operation to prevent duplicate transfers.
- Observability: Log transaction signatures, slot numbers, and post-transaction balances. Use BlockEden.xyz's websocket subscriptions to get real-time settlement signals for your application's backend.
- Compliance: Token-2022 provides primitives for compliance. If you need to implement features like the travel rule, the extension model allows you to do so cleanly, keeping your business logic separate from the token's core functionality.
Appendix A — Quick Reference
- Mint (Mainnet):
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo - Decimals:
6 - Token Program ID:
TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb - Background: PayPal announced Solana support on May 29, 2024.
- Official Docs: Solana Token Extensions, PayPal Developer Portal
Appendix B — Direct JSON-RPC Calls (curl)
Get Mint Account Info & Confirm Owner
This call retrieves the mint account data and lets you verify its owner is the Token-2022 program.
# Replace with your BlockEden.xyz RPC URL
curl -s -X POST "$SOLANA_RPC_URL" -H 'content-type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"getAccountInfo",
"params":["2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
{"encoding":"base64","commitment":"confirmed"}]
}'
# In the JSON response, the "owner" field should equal "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb".
List All PYUSD Token Accounts for a User
This is useful for wallets that need to discover all PYUSD holdings for a given user.
curl -s -X POST "$SOLANA_RPC_URL" -H 'content-type: application/json' -d '{
"jsonrpc":"2.0",
"id":1,
"method":"getTokenAccountsByOwner",
"params":[
"<OWNER_PUBLIC_KEY>",
{"mint":"2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo"},
{"encoding":"jsonParsed","commitment":"confirmed"}
]
}'
Ready to build? Grab your high-performance BlockEden.xyz RPC endpoint and start integrating the future of payments today.
