Skip to content

Xenian84/x1pays

Repository files navigation

X1Pays

AI payment infrastructure for X1 blockchain.

X1Pays enables AI agents to pay for API calls, trade tokens on xDEX, manage wallets, and enforce spending policies — all through the x402 payment protocol. Integrates with OpenClaw, MCP (Claude/Cursor), or use the SDK directly.

Architecture

graph LR
    subgraph agent ["What AI Agents Use"]
        OC[OpenClaw\n12 Tools, 5 Commands]
        MCP[MCP Server\nClaude, Cursor]
        SDK[SDK\nWalletManager, Policies]
        DEX[DEX\nSwaps, Quotes, Pools]
    end

    subgraph merchant ["What Merchants Use"]
        MW[Middleware\nExpress x402 Paywall]
    end

    subgraph infra ["X1Pays Infrastructure"]
        FAC[Facilitator\nx402 only: co-sign, pay gas]
        API[API Server\nFacilitator Registry]
    end

    OC --> SDK
    MCP --> SDK
    SDK --> DEX

    MW -->|verify and settle| FAC
    SDK -->|x402 payments| FAC
    API -->|discover| FAC

    SDK -->|send, swap| X1[X1 Chain]
    FAC -->|submit tx| X1
Loading

Packages

Package Description Version
@x1pay/sdk Core — WalletManager, AssetRegistry, SpendingPolicy, PaymentBuilder v0.4.0
@x1pay/dex xDEX integration — swaps, quotes, pool discovery, AMM math v0.1.0
@x1pay/middleware Express/Hono/Fastify/Next.js middleware for x402 paywalls v0.3.0
@x1pay/openclaw OpenClaw plugin — 12 tools, 5 commands, 3 skills v0.3.0
@x1pay/mcp MCP server for Claude Desktop, Cursor, and MCP-compatible agents v0.3.0
@x1pay/client Low-level x402 client utilities and facilitator discovery v0.2.0

Quick Start

1. AI Agent — Pay for resources

npm install @x1pay/sdk
import { WalletManager } from '@x1pay/sdk'

const wallet = new WalletManager(process.env.AGENT_KEY!, {
  network: 'x1-mainnet',
})

// Enforce spending limits
wallet.setPolicy({
  maxPerTransaction: 10_000_000n,   // 10 USDC.x max per tx
  sessionBudget: 100_000_000n,      // 100 USDC.x session cap
  allowedAssets: ['USDC.x'],          // Only USDC.x payments
})

// Pay for an x402-protected API (facilitator covers gas)
const result = await wallet.payForResource('https://api.example.com/premium/data')
console.log(result.data)     // API response
console.log(result.txHash)   // On-chain tx hash

// Check balances
const balances = await wallet.getBalances()
console.log(balances.USDC.x.uiAmount)  // 95.0

// Direct token transfer (agent pays gas)
await wallet.send('RecipientAddress...', '5.0', 'USDC.x')

2. Merchant — Paywall an API endpoint

npm install @x1pay/middleware
import express from 'express'
import { x402 } from '@x1pay/middleware'

const app = express()

app.use('/api/premium', x402({
  payTo: 'YOUR_WALLET_ADDRESS',
  amount: '100000',           // 0.1 USDC.x
  tokenMint: 'USDC.x',
  network: 'x1-mainnet',
  facilitatorUrl: 'https://x1pays.xyz/facilitator-alpha-mainnet',
}))

app.get('/api/premium/data', (req, res) => {
  res.json({ answer: 42, txHash: res.locals.txHash })
})

app.listen(3000)

3. DEX Trading

npm install @x1pay/dex
import { XDex } from '@x1pay/dex'

const dex = XDex.create('x1-mainnet')

// Get a quote
const quote = await dex.getQuote('USDC.x', 'WXNT', '10.0')
console.log(`Expected: ${quote.amountOut}, Impact: ${quote.priceImpact}%`)

// Execute swap (agent wallet pays gas)
const result = await dex.swap(wallet.keypair, 'USDC.x', 'WXNT', '10.0')
console.log(`TX: ${result.txHash}`)

// Price feed
const price = await dex.getPrice('WXNT', 'USDC.x')
console.log(`1 WXNT = ${price} USDC.x`)

// Discover pools
const pools = await dex.listPools()
console.log(`${pools.length} pools on xDEX`)

How x402 Works

sequenceDiagram
    participant C as Client
    participant S as Server
    participant F as Facilitator
    participant X as X1 Chain

    C->>S: GET /premium
    S-->>C: 402 Payment Required

    Note over C: Build tx and partial sign

    C->>F: POST /verify
    F-->>C: valid
    C->>F: POST /settle
    F->>X: Co-sign and submit
    X-->>F: Confirmed
    F-->>C: txHash

    C->>S: GET /premium with payment
    S-->>C: 200 OK with data
Loading
  1. Probe — Client requests the resource. Server responds HTTP 402 with payment terms.
  2. Sign — SDK builds a TransferChecked transaction, buyer partially signs it.
  3. Verify — Facilitator validates the transaction (correct amounts, programs, authority).
  4. Settle — Facilitator co-signs and submits on-chain. Buyer pays 0 gas.
  5. Access — Client sends the settled txHash and gets the resource.

Two Modes of Operation

X1Pays has two completely separate modes. The facilitator is only involved in x402 API payments. Everything else goes directly to the blockchain.

x402 API Payments (facilitator involved)

When an AI agent pays for a paywalled API, the facilitator co-signs and submits the transaction. The buyer pays 0 gas — the facilitator covers it. This is the only time the facilitator is involved.

Agent --> Merchant API --> Facilitator --> X1 Chain

Direct Operations (no facilitator)

When an agent sends tokens, swaps on xDEX, or checks balances, it talks directly to the X1 blockchain. No facilitator, no middleman. The agent's wallet pays its own gas.

Agent --> X1 Chain (direct)

Gas Model

Operation Facilitator involved? Who pays gas
payForResource() (x402 API payment) Yes Facilitator
wallet.send() (direct transfer) No Sender's wallet
dex.swap() (DEX trading) No Agent's wallet
wallet.getBalances() (read) No Free (RPC read)
dex.getQuote() (read) No Free (RPC read)

Supported Assets

Symbol Name Type Decimals Mint
XNT Native XNT Native 9
USDC.x USD Coin (X1) Token-2022 6 B69chRzqzDCmdB5WYB8NRu5Yv5ZA95ABiZcdzCgGm9Tq
WXNT Wrapped XNT SPL Token 9 So11111111111111111111111111111111111111112

OpenClaw Integration

npm install @x1pay/openclaw

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "x1pays": {
        "package": "@x1pay/openclaw",
        "config": {
          "privateKey": "YOUR_BASE58_KEY",
          "network": "x1-mainnet",
          "sessionBudget": 100000000,
          "maxPerTransaction": 10000000,
          "priceAlerts": true
        }
      }
    }
  }
}

Tools (12)

Tool Description
x1pays_balance Check wallet balances (XNT, USDC.x, WXNT)
x1pays_send Send tokens to any X1 address
x1pays_pay Pay for an x402-protected resource
x1pays_probe Check payment requirements without paying
x1pays_assets List supported assets and mints
x1pays_swap Swap tokens on xDEX
x1pays_quote Get a swap quote (preview without executing)
x1pays_price Get current token price from xDEX
x1pays_pools List all xDEX liquidity pools
x1pays_stats Session spending statistics
x1pays_portfolio Full portfolio overview with balances
x1pays_history Transaction history

Slash Commands (5)

Command Example
/balance Quick balance check
/swap <amount> <from> <to> /swap 10 USDC.x WXNT
/send <address> <amount> <asset> /send addr... 5 USDC.x
/price <token> /price WXNT
/portfolio Full portfolio view

Skills (3)

SKILL.md files that teach the agent best practices:

Skill What it teaches
x1pays Core payments — when to use balance, send, pay, probe
x1pays-trading DEX trading — always quote before swap, watch price impact, slippage
x1pays-defi Advanced DeFi — DCA with cron, price alerts, portfolio rebalancing

Background Services (2)

Service Description
Price Monitor Polls xDEX pools every 30s, triggers alerts on price conditions
Payment Listener Monitors incoming payments and x402 settlements

MCP Server (Claude / Cursor)

npm install -g @x1pay/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x1pays": {
      "command": "x1pays-mcp",
      "env": {
        "X1PAYS_PRIVATE_KEY": "your_base58_key",
        "X1PAYS_NETWORK": "x1-mainnet"
      }
    }
  }
}

Cursor

Add to MCP settings — same 12 tools are available for inline code payments and DeFi.

Run standalone

X1PAYS_PRIVATE_KEY=your_key X1PAYS_NETWORK=x1-mainnet x1pays-mcp

Spending Policies

Enforce strict limits on what your agent can spend:

wallet.setPolicy({
  maxPerTransaction: 1_000_000n,     // Max 1 USDC.x per tx
  sessionBudget: 10_000_000n,        // Max 10 USDC.x per session
  dailyBudget: 50_000_000n,          // Max 50 USDC.x per day
  allowedAssets: ['USDC.x'],           // Only USDC.x payments
  allowedRecipients: ['addr1...'],   // Whitelist recipients
})

const check = wallet.checkPolicy(1_000_000n, 'USDC.x', 'recipient...')
// { allowed: true } or { allowed: false, reason: "..." }

All amounts in atomic units (USDC.x: 6 decimals, so 1_000_000n = 1 USDC.x).


xDEX Program IDs

Network Program ID
Mainnet sEsYH97wqmfnkzHedjNcw3zyJdPvUmsa9AixhS4b4fN
Testnet 7EEuq61z9VKdkUzj7G36xGd7ncyz8KBtUwAWVjypYQHf

xDEX is a Raydium CP Swap fork running natively on X1.


Pricing

0.10% per transaction (10 basis points). No subscriptions, no minimum volume. Gas always covered by X1Pays for x402 payments.


Development

# Clone
git clone https://github.com/Xenian84/x1pays.git
cd x1pays

# Install
pnpm install

# Build all packages
pnpm run build

# Run tests (requires .env.test with wallet keys)
cp .env.test.example .env.test
# Edit .env.test with your test wallet keys

Project Structure

x1pays/
├── packages/
│   ├── sdk/           # Core SDK — WalletManager, payments, policies
│   ├── dex/           # xDEX — swaps, quotes, pools, AMM math
│   ├── middleware/     # Express/Hono/Fastify x402 middleware
│   ├── openclaw/      # OpenClaw plugin — 12 tools, 5 commands, 3 skills
│   ├── mcp/           # MCP server for Claude/Cursor
│   ├── client/        # Low-level x402 client utilities
│   ├── facilitator/   # Payment facilitator service
│   ├── api/           # REST API + facilitator registry
│   ├── shared/        # Shared types and utilities
│   ├── website/       # x1pays.xyz frontend
│   └── x402-x1-react/ # React components for x402
├── examples/          # Usage examples
├── README.md
├── CHANGELOG.md
└── LICENSE

Links

License

MIT

About

AI payment infrastructure for X1 blockchain. SDK, DEX, x402 middleware, OpenClaw plugin, MCP server.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors