Documentation

Everything you need to integrate PayXor into your Web3 application

Getting Started

PayXor provides a simple way to accept on-chain payments in your Web3 application. Follow these steps to get started:

1. Create an Account

Sign up for a PayXor account and create your first application. You'll receive an App ID and access tokens for admin endpoints.

2. Install the SDK

Or use yarn, pnpm, or your preferred package manager.

terminal

bash

1# Choose your preferred package manager
2npm install @payxor/sdk
3yarn add @payxor/sdk
4pnpm add @payxor/sdk

3. Initialize the Client

client.ts

typescript

1import { PayXorClient } from '@payxor/sdk';
2 
3const client = new PayXorClient({
4  // apiUrl: 'https://api.payxor.xyz', // Optional - defaults to production
5  walletClient: yourWagmiWalletClient, // Optional: for token approvals
6});

4. Generate a Quote

Create a quote on your backend using EIP-712 signing, then send it to your frontend.

quote.ts

typescript

1const { quote, sigBackend } = await client.getQuote({
2  appId: '0x...',      // Your app ID
3  productId: '0x...',  // Product ID to purchase
4  chainId: 8453,       // Base mainnet
5  payer: '0x...',      // User's wallet address
6  tokenAddress: '0x...', // Optional: specific stablecoin
7});

5. Process Payment

On the frontend, use the signed quote to initiate the payment.

payment.ts

typescript

1const txHash = await client.pay(quote, sigBackend, account, 8453);
2console.log('Payment successful:', txHash);
3 
4// Confirm with backend
5await client.confirmTransaction(txHash, quote.quoteId);

Packages

Choose the integration method that best fits your stack

React Hooks & Components

Pre-built hooks and unstyled components - try the interactive demo

Interactive

DropdownBuyButton

$9.99 USD

Select token

Click to simulate approval → payment flow

BuyButton.tsx

tsx

1import { useTokenPayment, usePayment, DropdownBuyButton } from "@payxor/react";
2import { useAccount, useChainId, usePublicClient, useWalletClient } from "wagmi";
3 
4function BuyButton({ appId, productId }) {
5  const { address } = useAccount();
6  const chainId = useChainId();
7  const publicClient = usePublicClient();
8  const { data: walletClient } = useWalletClient();
9 
10  const {
11    stablecoins,
12    selectedToken,
13    setSelectedToken,
14    needsApproval,
15    approve,
16    approving,
17  } = useTokenPayment({
18    appId,
19    productId,
20    address,
21    chainId,
22    publicClient,
23    walletClient,
24    // apiUrl: "https://api.payxor.xyz", // Optional - defaults to production
25  });
26 
27  const { executePayment, loading } = usePayment({
28    appId,
29    productId,
30    tokenAddress: selectedToken,
31    address,
32    chainId,
33    publicClient,
34    walletClient,
35    // apiUrl: "https://api.payxor.xyz", // Optional - defaults to production
36  });
37 
38  return (
39    <DropdownBuyButton
40      stablecoins={stablecoins}
41      selectedToken={selectedToken}
42      onSelect={setSelectedToken}
43      needsApproval={needsApproval}
44      onApprove={approve}
45      onBuy={executePayment}
46      loading={loading}
47      approving={approving}
48    />
49  );
50}

React Hooks

useTokenPayment, usePayment, and more

Unstyled Components

DropdownBuyButton, ProductCard, StatusBadge

Auto Approval Flow

Automatic token approval handling

Payment Modes

PayXor supports four payment modes, each designed for different use cases:

SESSION

mode: 0

Time-limited access to your application. Perfect for subscriptions or temporary premium features.

e.g., 1 hour premium access

FEATURE

mode: 1

One-time payment to unlock a specific feature permanently. Great for premium upgrades.

e.g., lifetime feature unlock

RECEIPT

mode: 2

Verifiable proof of purchase for digital goods. Each payment generates a unique receipt on-chain. Supports custom amounts for flexible pricing.

e.g., one-time purchase proof

PASS

mode: 3

Membership passes for exclusive access. Issue passes that grant ongoing privileges.

e.g., membership token

SDK Integration

The PayXor SDK provides a simple interface for integrating payments into your application.

Core Methods

getProductInfo(appId, productId)
getQuote(request)
pay(quote, sigBackend, account, chainId)
confirmTransaction(txHash, quoteId)
verifyReceipt(txHash, quoteId, chainId)

Entitlement Methods

isSessionActive(payer, appId, productId, chainId)
isFeatureUnlocked(payer, appId, entitlementId, chainId)
hasPass(payer, appId, passId, chainId)

Token Methods

getAvailableStablecoins(chainId)
getAppSupportedStablecoins(appId, chainId)
checkBalance(tokenAddress, owner, chainId)
checkAllowance(tokenAddress, owner, chainId)
approveToken(tokenAddress, amount, account, chainId)

Utility Methods

formatTokenAmount(amount, decimals)
parseTokenAmount(amount, decimals)
hasSufficientAllowance(token, owner, amount, chainId)

React Package

Use @payxor/react for wallet-agnostic hooks and unstyled UI components.

Hooks

usePayXorClient({ apiUrl, walletClient })
usePayment({ appId, productId, ... })
useTokenPayment({ appId, productId, ... })
useTokenApproval({ tokenAddress, ... })
useTokenStatuses({ stablecoins, ... })
useFeatureStatus({ appId, entitlementId, ... })
useSessionStatus({ appId, productId, ... })

Components

<Button />
<StatusMessage />
<StatusBadge />
<StablecoinSelector />
<ProductCard />
<DropdownBuyButton />

Component Styling

All components are unstyled by default. Use the slotClassNames prop to apply your own styles.

styling.tsx

tsx

<DropdownBuyButton
  slotClassNames={{
    container: "space-y-3",
    label: "text-sm font-medium text-gray-700",
    row: "flex items-stretch",
    selectWrapper: "relative flex-1",
    select: "w-full border rounded-l-lg px-4 py-2",
    selectIcon: "absolute right-2 top-1/2 -translate-y-1/2",
    button: "px-4 py-2 bg-blue-600 text-white rounded-r-lg",
  }}
/>

API Reference

Direct REST API endpoints for backend integration

POST/api/quote

Generate a signed quote for payment

POST/api/confirm-tx

Confirm transaction completion

GET/api/apps/{appId}/stablecoins

Get supported stablecoins

GET/api/products/{appId}/{productId}

Get product information

API Keys

Secure programmatic access to PayXor admin APIs with fine-grained permissions

Why Use API Keys?

API keys provide stable, long-lived authentication for programmatic access. Unlike session tokens that expire, API keys give you control over access scope and permissions, making them ideal for server-side integrations, CI/CD pipelines, and AI tools like MCP servers.

Creating API Keys

Go to Dashboard

Navigate to the API Keys page in your PayXor dashboard. API Keys

Create Key

Click "Create API Key" and give it a descriptive name.

Set Scope & Permissions

Choose scope (account or app-specific) and permissions (read or read-write).

Copy & Store

Copy the key immediately - it's only shown once!

Access Scopes

Full AccountFull Account Access

Access all apps and resources in your account. Best for server-side admin tools.

App-specificApp-Specific Access

Access only a single app and its products. Ideal for isolated deployments.

Permissions

Read & WriteFull Access

Create, update, and delete apps, products, and other resources.

Read OnlyView Only

View apps, products, quotes, and analytics. Cannot modify anything.

Using API Keys

authentication.sh

bash

1# API Key Authentication (Recommended)
2# Use the X-API-Key header with your API key
3curl -X GET "https://api.payxor.xyz/api/admin/apps" \
4  -H "X-API-Key: pxk_your_api_key_here"
5 
6# Bearer Token Authentication (Legacy)
7# Session tokens from dashboard login
8curl -X GET "https://api.payxor.xyz/api/admin/apps" \
9  -H "Authorization: Bearer your_session_token"

MCP Server Configuration

API keys are the recommended authentication method for MCP servers. They're more stable than session tokens and provide better security controls.

mcp.json

json

1// MCP configuration with API key (recommended)
2{
3  "mcpServers": {
4    "payxor-admin": {
5      "command": "npx",
6      "args": ["@payxor/mcp-admin"],
7      "env": {
8        "PAYXOR_API_KEY": "pxk_your_api_key_here"
9      }
10    }
11  }
12}

Usage Tracking

API keys track usage automatically. View read/write counts and last used timestamp in the dashboard to monitor activity and detect anomalies.

Read Count

GET requests

Write Count

POST/PUT/DELETE requests

Last Used

Activity timestamp

Security Best Practices

•Never expose API keys in client-side code - keys are for server-side use only
•Use app-specific scope when possible - limit blast radius if a key is compromised
•Use read-only permissions for monitoring - only grant write access when needed
•Revoke unused keys - regularly audit and revoke keys that are no longer needed
•Store keys securely - use environment variables or secrets managers, never commit to git

Secure by Default

Keys are hashed with SHA-256, never stored in plain text

Fine-Grained Control

Scope keys to specific apps with read-only or full access

Usage Analytics

Track read/write counts and monitor key usage over time

MCP Servers

Model Context Protocol servers for AI-powered integrations with Cursor, Claude Desktop, and other AI tools

AI-Powered Development

PayXor MCP servers enable AI assistants to interact with PayXor directly. Use natural language to manage apps, create products, process payments, and check entitlements.

@payxor/mcp-client

Client operations for payments and entitlements

terminal

bash

1# Install the MCP client package
2npm install @payxor/mcp-client
3# or use directly with npx
4npx @payxor/mcp-client

mcp.json

json

1// Add to your AI tool's MCP configuration
2// Cursor: .cursor/mcp.json
3// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
4{
5  "mcpServers": {
6    "payxor-client": {
7      "command": "npx",
8      "args": ["@payxor/mcp-client"]
9    }
10  }
11}

Payment Tools

get_quote(appId, productId, chainId, payer)
confirm_transaction(txHash, quoteId)
get_product_info(appId, productId)
get_app_stablecoins(appId, chainId)

Entitlement Tools

check_session(payer, appId, productId, chainId)
check_feature(payer, appId, entitlementId, chainId)
check_pass(payer, appId, passId, chainId)
check_balance(tokenAddress, owner, chainId)
check_allowance(tokenAddress, owner, chainId)

Available Resources

payxor://chainsList all supported blockchain networks
payxor://chains/{chainId}/stablecoinsStablecoins available on a chain
payxor://entitlementsHelp guide for entitlement checks

Available Prompts

Reusable templates that guide AI assistants through common PayXor workflows.

payment_flow
Complete Payment Flow
Guides through product info, balance/allowance checks, quote generation, and transaction confirmation.
check_entitlements
Check User Entitlements
Template for checking session, feature, or pass entitlements.
verify_payment_readiness
Verify Payment Readiness
Checks balance and allowance before getting a payment quote.

@payxor/mcp-admin

Admin operations for app and product management

terminal

bash

1# Install the MCP admin package
2npm install @payxor/mcp-admin
3# or use directly with npx (recommended: use API key)
4PAYXOR_API_KEY=pxk_your_key npx @payxor/mcp-admin

mcp.json

json

1// Add to your AI tool's MCP configuration
2// Recommended: Use API key from PayXor dashboard > API Keys
3{
4  "mcpServers": {
5    "payxor-admin": {
6      "command": "npx",
7      "args": ["@payxor/mcp-admin"],
8      "env": {
9        "PAYXOR_API_KEY": "pxk_your_api_key_here"
10      }
11    }
12  }
13}

App Management

list_apps()
get_app(id)
create_app(name, payee, ...)
update_app(id, ...)
delete_app(id)

Product Management

list_products(appId)
create_product(appId, name, mode, price)
update_product(id, ...)
delete_product(id)

Analytics

list_quotes(appId, filters)
get_stats(appId, productId?)

Developer Helper Tools

SDK documentation, usage examples, and integration snippets

Documentation Tools

getSdkOverview()
getSdkUsage(feature)
getReactComponentUsage(name)
listRecommendedFlows()

Code Generation

generateIntegrationSnippet(framework, productId?, appId?)

Available Helper Tools

getSdkOverview()

Returns comprehensive SDK documentation with authentication patterns, main methods, and initialization examples.

getSdkUsage(feature)

Get TypeScript examples for specific SDK features (getQuote, pay, checkBalance, approveToken, isSessionActive, etc.).

getReactComponentUsage(name)

Get props table and TSX usage examples for React components (DropdownBuyButton, ProductCard, StablecoinSelector, etc.).

generateIntegrationSnippet(framework, productId?, appId?)

Generate ready-to-paste integration code for Next.js, Vite, Remix, etc. Optionally includes product-specific details.

listRecommendedFlows()

Get recommended integration flows: Single Product Checkout, Cart Flow, Subscription Toggle, Feature Gating, Marketplace.

developer-helpers-example

text

1User: Show me how to use the DropdownBuyButton component
2 
3AI: [Uses getReactComponentUsage tool with name="DropdownBuyButton"]
4    Returns component documentation with props table, basic usage, and customization examples
5 
6User: Generate a Next.js integration snippet for my product
7 
8AI: [Uses generateIntegrationSnippet tool with framework="nextjs-app-router", productId="0x...", appId="..."]
9    Returns complete Next.js App Router integration code with wagmi setup and product-specific details
10 
11User: What are the recommended integration flows?
12 
13AI: [Uses listRecommendedFlows tool]
14    Returns comprehensive guide with 5 integration patterns and complete code examples

Available Resources

payxor://admin/appsList all apps owned by the authenticated user
payxor://admin/helpGuide for admin operations and available tools

Available Prompts

Reusable templates that help users talk to models in a consistent way. Prompts guide AI assistants through common admin workflows.

create_app
Create a New PayXor Application
Guides through creating a new app with proper configuration (name, payee, networks, stablecoins).
setup_product
Setup a New Product
Guides through creating a new product for an existing app with payment mode and pricing.
view_analytics
View App Analytics
Guides through viewing analytics, revenue stats, conversion rates, and top payers.
complete_app_setup
Complete App Setup
Complete workflow: create an app and set up multiple products in one go.
review_quotes
Review Payment Quotes
Guides through reviewing payment quotes with optional filters (product, status, chain, etc.).

API Key Authentication (Recommended)

Create an API key in the API Keys dashboard and use PAYXOR_API_KEY. . API keys are more stable than session tokens and support fine-grained permissions.

MCP Config File Locations

AI Tool	Config File Path
Cursor	`.cursor/mcp.json (project root)`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Continue	`~/.continue/config.json`
Cline	VS Code Command Palette → "Cline: MCP Servers"

Example AI Conversation

conversation

text

1User: Create a new app called "My Game" on Base network
2 
3AI: [Uses create_app tool]
4    Created app "My Game":
5    - App ID: 0x1234...
6    - Networks: Base (8453)
7    - Status: Active
8 
9User: Add a premium subscription for 5 USDC/month
10 
11AI: [Uses create_product tool]
12    Created product "Premium Subscription":
13    - Mode: SESSION
14    - Price: 5 USDC
15    - Duration: 30 days
16 
17User: Check if 0xabc... has an active subscription
18 
19AI: [Uses check_session tool]
20    Session is active, expires in 15 days.