@gullylabs/pay
v0.1.1
Published
Gully Pay SDK: the x402 payment facilitator client and Agent Wallets (pay HTTP 402s, verify receipts, MCP server for AI agents), plus wallet, routing and on-chain verification helpers for EVM chains, Gully Chain and Solana.
Maintainers
Readme
@gullylabs/pay
The Gully Pay SDK. Gully Pay (https://gullypay.xyz) is the payment gateway for every Gully product: x402 micropayments for APIs and AI agents, checkout, invoices and merchant stores, settled in USDC and ETH on Base, Ethereum, BNB Chain, Solana and Gully Chain Testnet (485590; Gully Chain mainnet is coming).
| Entry | What it is | Dependencies |
|---|---|---|
| @gullylabs/pay | x402 facilitator client (GullyPayClient), Agent Wallets (gullyPay.agent()), the 402 handshake (fetchWithPayment) | none |
| @gullylabs/pay/wallet | wallets, payment router, token registry, EVM on-chain verification and sends, treasury vault, agent wallet contract helpers | viem |
| @gullylabs/pay/solana | Solana USDC/USDT verification and SPL sends | @solana/web3.js + @solana/spl-token + viem |
| gullypay-agent-mcp (bin) | MCP server (stdio) so Claude and other agents pay through a Gully Pay agent wallet | none |
ESM and CommonJS builds with TypeScript types. Node 20+, Bun, Deno, edge runtimes and browsers (root entry).
It replaces the unpublished @gullypay/x402-sdk and @gullypay/wallet-sdk (same APIs).
5-minute quickstart
npm install @gullylabs/pay- Let an AI agent pay for an API by itself (an
agk_...key from the Agents page at https://gullypay.xyz; the owner's budget, daily cap and allowlists are enforced by Gully Pay and the wallet contract):
import { gullyPay } from '@gullylabs/pay'
const agent = gullyPay.agent(process.env.GULLYPAY_AGENT_KEY!)
const res = await agent.fetch('https://api.example.com/premium') // any x402 endpoint: 402 -> pay -> retry
console.log(await res.json())- Or drive the x402 facilitator yourself (a scoped
rk_...key from the developer dashboard):
import { GullyPayClient } from '@gullylabs/pay'
const client = new GullyPayClient({ facilitatorUrl: 'https://gullypay.xyz/api', apiKey: process.env.GULLYPAY_API_KEY })
const status = await client.status() // supported networks, assets, schemes
const paid = await client.fetchWithPayment('https://api.example.com/premium', async (req) => {
const { network, asset, amount, payTo } = req.accepts[0]
const txHash = await settleOnChain({ network, asset, amount, payTo }) // your wallet code
return client.pay({ resource: req.resource.url, network, amount, txHash, payerAddress: me })
})
await client.verify(receiptToken) // is a receipt still valid?- For Claude Desktop or any MCP host:
{ "mcpServers": { "gullypay": { "command": "npx", "args": ["-y", "-p", "@gullylabs/pay", "gullypay-agent-mcp"], "env": { "GULLYPAY_AGENT_KEY": "agk_..." } } } }Tools: x402_pay, gullypay_checkout, gullypay_agent_status. Docs: https://gullypay.xyz/docs/agents
Try it without a key
import { GullyPayClient } from '@gullylabs/pay'
const client = new GullyPayClient({ facilitatorUrl: 'https://gullypay.xyz/api' })
const s = await client.status()
console.log(s.supportedNetworks) // [ 'base', 'base-sepolia', 'ethereum', 'bsc', 'solana', 'gully-chain-testnet' ]Wallet helpers
npm install @gullylabs/pay viem # + @solana/web3.js @solana/spl-token for @gullylabs/pay/solanaimport { verifyStablecoinPayment, getToken, isNativeAsset, DEFAULT_CONFIRMATIONS } from '@gullylabs/pay/wallet'
getToken('base', 'USDC') // { address, decimals: 6 }; USDC on BSC has 18 decimals
isNativeAsset('gully-chain-testnet', 'ETH') // true: a plain value transfer, not a token Transfer log
const r = await verifyStablecoinPayment({ network: 'gully-chain-testnet', rpcUrl: 'https://rpc.gullychain.xyz', txHash, payTo, asset: 'ETH', minAmount })Verification fails closed: anything not positively verified (unknown network or asset, missing or failed tx, RPC error) is verified: false. On Gully Chain Testnet the sequencer receipt is the confirmation (DEFAULT_CONFIRMATIONS['gully-chain-testnet'] = 0n).
Errors
Facilitator failures are X402FacilitatorError (operation, status, detail from the server). Agent failures are AgentPaymentError (status, code).
Links
- Gully Pay docs: https://gullypay.xyz/docs (x402: https://gullypay.xyz/docs/x402, agents: https://gullypay.xyz/docs/agents)
- Integrate every Gully SDK in 5 minutes: https://docs.gullychain.xyz/sdks/ and https://docs.gullylabs.xyz/integrate
- Status and supported networks, live: https://gullypay.xyz/api/x402/status
MIT. Built and run by Gully Labs.
