Skip to content

solana-pay

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

solana-pay

README.md

@gillsdk/solana-pay

modern and type-safe Solana Pay protocol client library, built on top of gill

Overview

@gillsdk/solana-pay is a complete, type-safe implementation of the Solana Pay specification. Solana Pay is a standardized protocol for encoding transaction requests within URLs, enabling seamless payments and blockchain interactions across the Solana ecosystem.

Key Features:

  • Transfer Requests: Create payment URLs for SOL and SPL tokens with optional reference tracking
  • Transaction Requests: Build interactive checkout flows with HTTPS endpoints
  • URL Parsing: Parse and validate any Solana Pay URL with full type safety
  • Response Handling: Fetch and validate merchant information and transactions
  • Comprehensive Validation: Built-in security checks including HTTPS enforcement, URL length validation, and input validation

Installation

Install @gillsdk/solana-pay with your package manager of choice:

npm install gill @gillsdk/solana-pay
pnpm add gill @gillsdk/solana-pay
yarn add gill @gillsdk/solana-pay

Documentation

For comprehensive documentation, examples, and best practices, see the Solana Pay guide.

Additional resources:

Request Types

Solana Pay supports two distinct request types:

Transfer Requests - Non-interactive payment URLs with all details encoded directly:

  • Best for: Simple payments, invoices, QR codes
  • No server required
  • Example: solana:recipient?amount=1.5&label=Coffee+Shop

Transaction Requests - Interactive URLs pointing to HTTPS endpoints:

  • Best for: Complex transactions, merchant checkouts, dynamic pricing
  • Requires server-side implementation
  • Example: solana:https://merchant.example.com/api

See the Request Types documentation for detailed comparison.

API Reference

Function Purpose Documentation
encodeSolanaPayURL Create transfer or transaction request URLs Transfer Requests, Transaction Requests
parseSolanaPayURL Parse and validate any Solana Pay URL Parsing URLs
solanaPayTransactionRequest.get Fetch merchant info (GET request) Fetching Merchant Information
solanaPayTransactionRequest.post Request transaction (POST request) Requesting a Transaction
parseSolanaPayGetResponse Validate GET response data Validating GET Responses
parseSolanaPayPostResponse Validate POST response data Validating POST Responses

Quick Start

Transfer Request (Simple Payment)

import { encodeSolanaPayURL } from "@gillsdk/solana-pay";
import { address } from "gill";

// Create a payment request for 1.5 SOL
const url = encodeSolanaPayURL({
  recipient: address("nick6zJc6HpW3kfBm4xS2dmbuVRyb5F3AnUvj5ymzR5"),
  amount: 1.5,
  label: "Coffee Shop",
  message: "Payment for espresso",
});
// → "solana:nick6zJc6HpW3kfBm4xS2dmbuVRyb5F3AnUvj5ymzR5?amount=1.5&label=Coffee+Shop&message=Payment+for+espresso"

Transaction Request (Interactive Checkout)

import { encodeSolanaPayURL, solanaPayTransactionRequest } from "@gillsdk/solana-pay";
import { address } from "gill";

// Create a transaction request URL
const url = encodeSolanaPayURL({
  link: new URL("https://merchant.example.com/api"),
  label: "Example Merchant",
  message: "Purchase item #42",
});

// Fetch merchant information (GET request)
const { label, icon } = await solanaPayTransactionRequest.get(new URL("https://merchant.example.com/api"));

// Request transaction (POST request)
const { transaction, message } = await solanaPayTransactionRequest.post(new URL("https://merchant.example.com/api"), {
  account: address("nick6zJc6HpW3kfBm4xS2dmbuVRyb5F3AnUvj5ymzR5"),
});