SDKs

Published on npm today: @gullypay/x402-sdk (x402 micropayments) and @gullypay/wallet-sdk (account-abstraction wallet + payment routing). The unified @gullypay/sdk, gullypay (Python), gullypay-go, and @gullypay/react-native-sdk packages are in active development — the snippets below describe their target API.

npm install @gullypay/sdk

1import { GullyPay } from '@gullypay/sdk';
2
3const gullypay = new GullyPay({
4apiKey: process.env.GULLYPAY_API_KEY!,     // rk_live_... or rk_test_...
5environment: 'production',                // 'production' | 'sandbox'
6timeout: 30000,                           // Request timeout in ms (default: 30s)
7retries: 3,                               // Auto-retry on 5xx errors (default: 3)
8});

1// Create a payment intent
2const intent = await gullypay.payments.create({
3amount: 4999,              // $49.99 in cents
4currency: 'USD',
5storeId: 'store_abc123',
6merchantId: 'merch_xyz789',
7customerEmail: '[email protected]',
8idempotencyKey: 'order-001',
9});
10
11// Confirm the payment
12const confirmed = await gullypay.payments.confirm(intent.id);
13
14// Retrieve a transaction
15const tx = await gullypay.payments.get('pi_abc123');
16
17// List transactions for a merchant
18const transactions = await gullypay.payments.list('merch_xyz789');
19
20// Refund a payment (full)
21const refund = await gullypay.payments.refund('pi_abc123');
22
23// Refund a payment (partial)
24const partialRefund = await gullypay.payments.refund('pi_abc123', {
25amount: 1000,           // Refund $10.00
26reason: 'Item returned',
27});

1// Create a merchant
2const merchant = await gullypay.merchants.create({
3name: 'Acme Electronics',
4slug: 'acme-electronics',
5businessType: 'company',
6country: 'US',
7});
8
9// List your merchants
10const merchants = await gullypay.merchants.list();
11
12// Get merchant details
13const details = await gullypay.merchants.get('merch_xyz789');
14
15// Update a merchant
16await gullypay.merchants.update('merch_xyz789', {
17businessType: 'retail',
18});
19
20// Add a store
21const store = await gullypay.merchants.createStore('merch_xyz789', {
22name: 'West Coast Store',
23domain: 'west.acme.com',
24currency: 'USD',
25timezone: 'America/Los_Angeles',
26});
27
28// Initiate Stripe Connect onboarding
29const onboarding = await gullypay.merchants.onboard('merch_xyz789');
30console.log(onboarding.url); // Redirect merchant to Stripe

1// Create a product
2const product = await gullypay.products.create('store_abc123', {
3title: 'Wireless Headphones Pro',
4description: 'Premium noise-canceling headphones',
5type: 'physical',
6price: 14999,
7sku: 'WHP-001',
8status: 'active',
9});
10
11// List products
12const products = await gullypay.products.list('store_abc123');
13
14// Create an order
15const order = await gullypay.orders.create('store_abc123', {
16customerId: 'cust_abc123',
17items: [
18  { variantId: 'var_xyz789', quantity: 2 },
19],
20currency: 'USD',
21});
22
23// Fulfill an order
24await gullypay.orders.fulfill('ord_abc123');
25
26// Cancel an order
27await gullypay.orders.cancel('ord_abc123');

1// Create a hosted checkout session
2const session = await gullypay.checkout.createHosted('store_abc123', {
3amount: 2999,
4currency: 'USD',
5successUrl: 'https://yoursite.com/success',
6cancelUrl: 'https://yoursite.com/cancel',
7});
8
9console.log(session.url);
10// https://checkout.gullypay.xyz/cs_abc123
11
12// Retrieve checkout session data
13const sessionData = await gullypay.checkout.get('cs_abc123');

1// Create a wallet
2const wallet = await gullypay.wallets.create({ chain: 'base' });
3
4// Get your wallets
5const wallets = await gullypay.wallets.listMine();
6
7// Send stablecoins
8await gullypay.wallets.send(wallet.id, {
9toAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD38',
10amount: 100.50,
11currency: 'USDC',
12});
13
14// Swap tokens
15await gullypay.wallets.swap(wallet.id, {
16fromToken: 'USDC',
17toToken: 'glUSD',
18amount: 500,
19});
20
21// Get transaction history
22const history = await gullypay.wallets.getHistory(wallet.id);

1import { GullyPay, GullyPayError, RateLimitError, AuthenticationError } from '@gullypay/sdk';
2
3try {
4const payment = await gullypay.payments.create({ /* ... */ });
5} catch (error) {
6if (error instanceof AuthenticationError) {
7  // Invalid or expired API key
8  console.error('Authentication failed:', error.message);
9} else if (error instanceof RateLimitError) {
10  // Too many requests -- retry after error.retryAfter seconds
11  console.error(`Rate limited. Retry after ${error.retryAfter}s`);
12} else if (error instanceof GullyPayError) {
13  // General API error
14  console.error(`API error ${error.statusCode}: ${error.message}`);
15  console.error('Details:', error.details);
16} else {
17  // Network error, timeout, etc.
18  throw error;
19}
20}

pip install gullypay

1from gullypay import GullyPay
2
3client = GullyPay(
4  api_key="rk_live_your_api_key",
5  environment="production",  # "production" or "sandbox"
6  timeout=30,                # seconds
7  max_retries=3,
8)

1# Create a payment intent
2intent = client.payments.create(
3  amount=2499,
4  currency="USD",
5  store_id="store_abc123",
6  merchant_id="merch_xyz789",
7  customer_email="[email protected]",
8)
9
10# Confirm the payment
11confirmed = client.payments.confirm(intent.id)
12print(f"Payment status: {confirmed.status}")
13
14# Refund (full)
15refund = client.payments.refund("pi_abc123")
16
17# Refund (partial)
18partial_refund = client.payments.refund(
19  "pi_abc123",
20  amount=1000,
21  reason="Damaged in shipping",
22)

1# Create a product
2product = client.products.create(
3  store_id="store_abc123",
4  title="Python Programming Guide",
5  type="digital",
6  price=1999,
7  status="active",
8)
9
10# Create an order
11order = client.orders.create(
12  store_id="store_abc123",
13  customer_id="cust_abc123",
14  items=[
15      {"variant_id": "var_xyz789", "quantity": 1},
16  ],
17)
18
19# Fulfill the order
20client.orders.fulfill(order.id)

1from gullypay import GullyPayClient
2
3x402_client = GullyPayClient(
4  facilitator_url="https://gullypay.xyz/api",
5  api_key="rk_live_your_api_key",
6)
7
8# Pay for a resource
9receipt = x402_client.pay(
10  resource="https://api.example.com/ai/generate",
11  tx_hash="0x7d1afa7b...",
12  network="base",
13  amount="100",
14  payer_address="0x742d35Cc...",
15)
16
17# Verify a receipt
18result = x402_client.verify(receipt.token)
19print(f"Valid: {result.valid}")

1import asyncio
2from gullypay import AsyncGullyPay
3
4async def main():
5  client = AsyncGullyPay(api_key="rk_live_your_api_key")
6
7  # All methods support async/await
8  intent = await client.payments.create(
9      amount=2499,
10      currency="USD",
11      store_id="store_abc123",
12      merchant_id="merch_xyz789",
13  )
14
15  confirmed = await client.payments.confirm(intent.id)
16  print(f"Status: {confirmed.status}")
17
18asyncio.run(main())

go get github.com/jinklabs/gullypay-go

1package main
2
3import (
4"context"
5"fmt"
6"log"
7
8"github.com/jinklabs/gullypay-go"
9)
10
11func main() {
12client := gullypay.NewClient(
13	gullypay.WithAPIKey("rk_live_your_api_key"),
14	gullypay.WithEnvironment(gullypay.Production),
15	gullypay.WithTimeout(30 * time.Second),
16)
17
18ctx := context.Background()
19
20// Create a payment intent
21intent, err := client.Payments.Create(ctx, &gullypay.CreatePaymentParams{
22	Amount:     2499,
23	Currency:   "USD",
24	StoreID:    "store_abc123",
25	MerchantID: "merch_xyz789",
26})
27if err != nil {
28	log.Fatal(err)
29}
30
31fmt.Printf("Payment ID: %s
32", intent.ID)
33
34// Confirm the payment
35confirmed, err := client.Payments.Confirm(ctx, intent.ID)
36if err != nil {
37	log.Fatal(err)
38}
39
40fmt.Printf("Status: %s
41", confirmed.Status)
42}

1// Create a merchant
2merchant, err := client.Merchants.Create(ctx, &gullypay.CreateMerchantParams{
3Name:         "Go Store",
4Slug:         "go-store",
5BusinessType: "company",
6Country:      "US",
7})
8
9// Create a product
10product, err := client.Products.Create(ctx, "store_abc123", &gullypay.CreateProductParams{
11Title:  "Go Gopher Sticker Pack",
12Type:   "physical",
13Price:  799,
14Status: "active",
15})
16
17// List products
18products, err := client.Products.List(ctx, "store_abc123")

1intent, err := client.Payments.Create(ctx, params)
2if err != nil {
3var apiErr *gullypay.Error
4if errors.As(err, &apiErr) {
5	switch apiErr.StatusCode {
6	case 401:
7		log.Fatal("Invalid API key")
8	case 429:
9		log.Printf("Rate limited, retry after %ds", apiErr.RetryAfter)
10	default:
11		log.Printf("API error %d: %s", apiErr.StatusCode, apiErr.Message)
12	}
13} else {
14	// Network or other error
15	log.Fatal(err)
16}
17}

npx expo install @gullypay/react-native-sdk

1import { GullyPayProvider } from '@gullypay/react-native-sdk';
2
3export default function App() {
4return (
5  <GullyPayProvider
6    apiKey="rk_live_your_api_key"
7    environment="production"
8  >
9    <YourApp />
10  </GullyPayProvider>
11);
12}

1import {
2usePayments,
3useMerchant,
4useWallet,
5useCheckout,
6} from '@gullypay/react-native-sdk';
7
8function PaymentScreen() {
9const { createIntent, confirmPayment, loading } = usePayments();
10const { merchant } = useMerchant();
11
12const handlePayment = async () => {
13  const intent = await createIntent({
14    amount: 2499,
15    currency: 'USD',
16    storeId: merchant.stores[0].id,
17    merchantId: merchant.id,
18  });
19
20  const result = await confirmPayment(intent.id);
21
22  if (result.status === 'succeeded') {
23    Alert.alert('Success', 'Payment completed!');
24  }
25};
26
27return (
28  <View>
29    <Text>Total: $24.99</Text>
30    <Button
31      title={loading ? 'Processing...' : 'Pay Now'}
32      onPress={handlePayment}
33      disabled={loading}
34    />
35  </View>
36);
37}

1import { useCheckout, CheckoutSheet } from '@gullypay/react-native-sdk';
2
3function ProductScreen({ product }) {
4const { openCheckout, isOpen, sessionUrl } = useCheckout();
5
6return (
7  <View>
8    <Text>{product.title}</Text>
9    <Text>${(product.price / 100).toFixed(2)}</Text>
10
11    <Button
12      title="Buy Now"
13      onPress={() => openCheckout({
14        amount: product.price,
15        currency: 'USD',
16        storeId: product.storeId,
17      })}
18    />
19
20    <CheckoutSheet
21      visible={isOpen}
22      url={sessionUrl}
23      onComplete={(result) => {
24        console.log('Checkout result:', result);
25      }}
26    />
27  </View>
28);
29}

1import { useWallet } from '@gullypay/react-native-sdk';
2
3function WalletScreen() {
4const { wallet, balance, send, swap, transactions } = useWallet();
5
6const handleSend = async () => {
7  await send({
8    toAddress: '0x742d35Cc...',
9    amount: 50,
10    currency: 'USDC',
11  });
12};
13
14return (
15  <View>
16    <Text>Balance: {balance.USDC} USDC</Text>
17    <FlatList
18      data={transactions}
19      renderItem={({ item }) => (
20        <Text>{item.type}: {item.amount} {item.currency}</Text>
21      )}
22    />
23    <Button title="Send $50 USDC" onPress={handleSend} />
24  </View>
25);
26}

npm install @gullypay/x402-sdk

1import { GullyPayClient } from '@gullypay/x402-sdk';
2
3const client = new GullyPayClient({
4facilitatorUrl: 'https://gullypay.xyz/api',
5apiKey: 'rk_live_your_api_key',
6});
7
8// Automatic 402 detection and payment
9const response = await client.fetchWithPayment(
10'https://api.example.com/ai/generate',
11async (requirements) => {
12  // The SDK provides the payment requirements from the 402 response
13  // You execute the on-chain payment and return the receipt
14  return client.pay({
15    resource: requirements.resourceUrl,
16    txHash: '0x...',
17    network: requirements.network,
18    amount: requirements.price,
19    payerAddress: '0x742d35Cc...',
20  });
21},
22);
23
24const data = await response.json();

The TypeScript and React Native SDKs include full type definitions for all request and response objects. Enable strict mode in your tsconfig.json for the best development experience.