### Install Dependencies and Start Development Server

Source: https://github.com/solana-foundation/pay/blob/main/pdb/README.md

Commands to install project dependencies and start the Express backend and Vite frontend development servers.

```bash
pnpm install
pnpm dev        # starts Express (port 3000) + Vite (port 5173)
```

--------------------------------

### Install Dependencies for Point of Sale App

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/examples/point-of-sale/README.md

Navigate to the point of sale example directory and install project dependencies using npm.

```shell
cd solana-pay/examples/point-of-sale
npm install
```

--------------------------------

### Setup Local Surfpool and Server

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Instructions for setting up a local Surfpool instance and configuring the example server to connect to it. This is an alternative to using the public sandbox.

```bash
# Install and start Surfpool
curl -sL https://run.surfpool.run/ | bash
surfpool start

# Point the server at localhost
RPC_URL=http://localhost:8899 pnpm dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/solana-foundation/pay/blob/main/CONTRIBUTING.md

Run this command to install all project dependencies. Ensure Just, Rust, Solana CLI, and Node.js with pnpm are installed.

```shell
just install
```

--------------------------------

### Quick Start: Generate Keypair and Make Paid API Call

Source: https://github.com/solana-foundation/pay/blob/main/README.md

A quick start guide to generate a keypair (with biometric protection on macOS) and then make a paid API call using the '--sandbox' flag for an ephemeral funded keypair.

```sh
# 1. Generate a keypair (Touch ID protected on macOS)
pay setup

# 2. Make a paid API call (--sandbox uses an ephemeral funded keypair)
pay --sandbox curl https://payment-debugger.vercel.app/mpp/quote/AAPL

# 3. Or let your AI agent handle it
pay --sandbox claude
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/README.md

Run this command to install all necessary project dependencies.

```bash
$ npm install
```

--------------------------------

### Cloud Run Pay Server Start Command

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Example command to start the Pay server on Cloud Run, specifying the provider spec, bind address, OpenAPI spec path, and OTLP sidecar.

```sh
pay server start /app/providers/google/bigquery.yml \
  --bind 0.0.0.0:8080 \
  --openapi /app/providers/google/bigquery.json \
  --otlp-sidecar 127.0.0.1:4318
```

--------------------------------

### GET Response Example

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/SPEC.md

Example of a successful GET request response, including label and icon.

```APIDOC
## GET Response

### Success Response (200)

- **label** (string) - The label for the payment.
- **icon** (string) - The URL of the icon for the payment.

### Response Example
```json
{
  "label":"Michael Vines",
  "icon":"https://example.com/icon.svg"
}
```
```

--------------------------------

### Install Pay from Source

Source: https://github.com/solana-foundation/pay/blob/main/README.md

Clone the 'pay' repository and use the provided 'just' commands to install the tool from its source code.

```sh
git clone https://github.com/solana-foundation/pay.git
cd pay
just install pay
```

--------------------------------

### Install and Run Server Dependencies

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Installs project dependencies and provides commands to run the server in watch mode or a single run. Assumes Node.js 20+ is installed.

```bash
pnpm install
pnpm dev      # watch mode — restarts on file changes
pnpm start    # single run
```

--------------------------------

### Start Local Development Server

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/examples/point-of-sale/README.md

Run this command to start the local development server for the point of sale app.

```shell
npm run dev
```

--------------------------------

### Install @solana/pay and @solana/kit

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/core/README.md

Install the necessary packages for Solana Pay and its core dependencies.

```bash
npm install @solana/pay @solana/kit
```

--------------------------------

### Solana Pay GET Response Example

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/SPEC.md

Shows a successful HTTP 200 OK response for a GET request, containing label and icon information.

```http
HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Content-Length: 62
Content-Encoding: gzip

{"label":"Michael Vines","icon":"https://example.com/icon.svg"}
```

--------------------------------

### Install @solana/pay

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/core/OVERVIEW.md

Install the Solana Pay library using pnpm.

```shell
pnpm add @solana/pay
```

--------------------------------

### Verify Pay Installation

Source: https://github.com/solana-foundation/pay/blob/main/README.md

Check the installed version of the 'pay' CLI tool to confirm a successful installation.

```sh
pay --version
```

--------------------------------

### API Request Handler Setup

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/core/transaction-request/MERCHANT_INTEGRATION.md

Set up the main API handler to manage incoming requests, directing GET and POST requests to their respective functions. This ensures only supported HTTP methods are processed.

```javascript
const index = async (request, response) => {
    // We set up our handler to only respond to `GET` and `POST` requests.
    if (request.method === 'GET') return get(request, response);
    if (request.method === 'POST') return post(request, response);

    throw new Error(`Unexpected method ${request.method}`);
};
```

--------------------------------

### Install Pay using Homebrew

Source: https://github.com/solana-foundation/pay/blob/main/README.md

Install the 'pay' CLI tool using the Homebrew package manager on macOS.

```sh
brew install pay
```

--------------------------------

### Solana Pay GET Request Example

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/SPEC.md

Illustrates the structure of a GET request to the Solana Pay endpoint, including order identification.

```http
GET /solana-pay?order=12345 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
```

--------------------------------

### Start Local Development Server

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/README.md

This command starts a local development server and automatically opens the website in your browser. Changes are typically reflected live without requiring a server restart.

```bash
$ npm start
```

--------------------------------

### Combined Client Setup and Usage

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/core/README.md

Use `createSolanaPayClient` to initialize a client that provides both merchant and wallet functionalities.

```typescript
import { createSolanaPayClient } from '@solana/pay';

const client = createSolanaPayClient({
  rpcUrl: 'https://api.devnet.solana.com',
  payer: myWalletSigner,
});

const url = client.pay.encodeURL({ recipient, amount: 1 });
const instructions = await client.pay.createTransfer({ recipient, amount: 1 });
await client.sendTransaction(instructions);
```

--------------------------------

### Initialize Keypair with Pay Setup

Source: https://context7.com/solana-foundation/pay/llms.txt

Initializes a keypair stored in the OS-native credential store. Supports interactive setup, forcing re-creation, specifying backends like Apple Keychain or 1Password, and file-based keypairs for CI. Use `pay --version` and `pay account list` to verify after setup.

```sh
pay setup
```

```sh
pay setup --force --backend AppleKeychain
```

```sh
pay setup --backend OnePassword --vault "Personal"
```

```sh
pay setup --backend File
```

```sh
pay --version
pay account list
```

--------------------------------

### POST Request Example

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/SPEC.md

Example of a POST request to the Solana Pay endpoint, including query parameters and request body.

```APIDOC
## POST Request

### Method
POST

### Endpoint
/solana-pay?order=12345

### Request Body
- **account** (string) - The account to send the payment to.

### Request Example
```json
{
  "account":"mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN"
}
```
```

--------------------------------

### Wallet Client Setup and Usage

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/core/README.md

Initialize a wallet client to parse payment URLs, create transfers, and send transactions. This client includes a transaction planner and executor.

```typescript
import { createWalletClient } from '@solana/pay';

const wallet = createWalletClient({
  rpcUrl: 'https://api.devnet.solana.com',
  payer: myWalletSigner,
});

// Parse a Solana Pay URL and send the payment
const parsed = wallet.pay.parseURL(url);
const instructions = await wallet.pay.createTransfer({
  recipient: parsed.recipient,
  amount: parsed.amount,
});
await wallet.sendTransaction(instructions);
```

--------------------------------

### POST Response Example

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/SPEC.md

Example of a successful POST request response, including a message and transaction details.

```APIDOC
## POST Response

### Success Response (200)

- **message** (string) - A confirmation message.
- **transaction** (string) - The transaction details.

### Response Example
```json
{
  "message":"Thanks for all the fish",
  "transaction":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAECC4JMKqNplIXybGb/GhK1ofdVWeuEjXnQor7gi0Y2hMcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQECAAAMAgAAAAAAAAAAAAAA"
}
```
```

--------------------------------

### Start MCP Server

Source: https://context7.com/solana-foundation/pay/llms.txt

Starts the MCP server on stdio, used by AI agents or other MCP-compatible hosts. Configuration can be done via command-line arguments or a JSON configuration file, specifying command, arguments, and environment variables.

```sh
pay mcp
```

```json
{
  "mcpServers": {
    "pay": {
      "command": "/usr/local/bin/pay",
      "args": ["mcp"],
      "env": {
        "PAY_ACTIVE_ACCOUNT": "myaccount",
        "PAY_NETWORK_ENFORCED": "mainnet"
      }
    }
  }
}
```

--------------------------------

### Start Pay Server with OpenAPI Spec

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Starts the Pay server using a provided YAML configuration and an OpenAPI JSON document. The gateway will serve a filtered and URL-rewritten version of the OpenAPI spec.

```sh
pay server start provider.yml --openapi openapi.json
```

--------------------------------

### Production Pay Server Configuration

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Example YAML fragment for configuring the Pay server in a production environment. Ensure sensitive values are injected as environment variables.

```yaml
operator:
  currencies:
    usd: ["USDC", "USDT", "CASH"]
  network: mainnet
  fee_payer: true
  rpc_url: "${PAY_RPC_URL}"
  recipient: "${PAY_PAYMENT_RECIPIENT}"
  signer:
    backend: gcp-kms
    key_name: "${PAY_GCP_KMS_KEY_NAME}"
    pubkey: "${PAY_GCP_KMS_PUBKEY}"
```

--------------------------------

### Start Payment Gateway Server

Source: https://context7.com/solana-foundation/pay/llms.txt

Starts a payment gateway proxy from a YAML specification. Supports custom bind addresses, recipients, RPC URLs, and OpenAPI spec generation. The `--debugger` flag enables an embedded Payment Debugger UI.

```sh
pay server start spec.yml
```

```sh
pay server start spec.yml --bind 0.0.0.0:8080 --recipient <WALLET_ADDRESS>
```

```sh
pay server start --debugger spec.yml
```

```sh
pay server start spec.yml --rpc-url https://api.mainnet-beta.solana.com
```

```sh
pay server start spec.yml --openapi openapi.json --public-url https://api.example.com
```

```sh
pay server demo
```

```sh
pay server scaffold --name my-api --path ./my-api
```

--------------------------------

### Run Local Pay Command

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Example command to interact with the local 'pay' service when running a local Surfpool instance. It demonstrates querying for a quote.

```bash
pay --local curl http://localhost:3402/mpp/quote/SOL
```

--------------------------------

### Merchant Client Setup and Usage

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/core/README.md

Initialize a merchant client to encode payment URLs, generate QR codes, and find/validate transactions. No signer is required for these operations.

```typescript
import { address } from '@solana/kit';
import { createMerchantClient } from '@solana/pay';

const merchant = createMerchantClient({
  rpcUrl: 'https://api.devnet.solana.com',
});

const recipient = address('MERCHANT_WALLET_ADDRESS');
const reference = address('UNIQUE_REFERENCE_ADDRESS');

// Encode a payment URL and show as QR code
const url = merchant.pay.encodeURL({ recipient, amount: 1, reference });
const qr = merchant.pay.createQR(url);

// After customer pays, find and validate the transaction
const found = await merchant.pay.findReference(reference);
await merchant.pay.validateTransfer(found.signature, { recipient, amount: 1, reference });
```

--------------------------------

### Clone Solana Pay Repository with Git

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/examples/point-of-sale/README.md

Use this command to clone the Solana Pay repository if you have Git installed.

```shell
git clone https://github.com/solana-labs/solana-pay.git
```

--------------------------------

### Provider Markdown File Structure

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Example file paths for defining provider configurations in the pay-skills repository. Use a three-level path when the gateway proxies another provider.

```text
providers/<operator>/<name>.md
providers/<operator>/<origin>/<name>.md
```

--------------------------------

### Query MPP Endpoint for Weather

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Example command to query an MPP endpoint for weather data using the 'pay' tool. This uses the sandbox environment.

```bash
pay --sandbox curl http://localhost:3402/mpp/weather/paris
```

--------------------------------

### Manage TypeScript SDK

Source: https://github.com/solana-foundation/pay/blob/main/CONTRIBUTING.md

Commands for managing the TypeScript SDK, including installing dependencies, building, linting, formatting, type checking, and running tests.

```shell
just ts install            # Install pnpm dependencies
```

```shell
just ts build              # Build the core package
```

```shell
just ts lint               # Check lint + formatting
```

```shell
just ts fmt               # Auto-fix formatting + lint
```

```shell
just ts typecheck          # Typecheck
```

```shell
just ts test               # Run tests
```

```shell
just ts test-watch         # Run tests in watch mode
```

--------------------------------

### Query x402 Endpoint for Joke

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Example command to query an x402 (Payment Required) endpoint for a joke using the 'pay' tool. This uses the sandbox environment.

```bash
pay --sandbox curl http://localhost:3402/x402/joke
```

--------------------------------

### Clone Solana Pay Repository with GitHub CLI

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/examples/point-of-sale/README.md

Use this command to clone the Solana Pay repository if you have the GitHub CLI installed.

```shell
gh repo clone solana-labs/solana-pay
```

--------------------------------

### Solana Pay POST Request Example

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/SPEC.md

Demonstrates a POST request to Solana Pay, including the order ID and the user's account information in JSON format.

```http
POST /solana-pay?order=12345 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
Content-Type: application/json
Content-Length: 57

{"account":"mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN"}
```

--------------------------------

### Run Local SSL Proxy

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/examples/point-of-sale/README.md

In a separate terminal, run this command to start a local SSL proxy, which may be required for the app to function correctly.

```shell
npm run proxy
```

--------------------------------

### Configure API Splits and Metering

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Set up API endpoints with specific metering dimensions and revenue splits. This example defines a partner recipient and distributes 20% of the revenue for the 'v1/report' endpoint to them.

```yaml
recipients:
  partner:
    account: "${PARTNER_WALLET}"
    label: "Partner"

endpoints:
  - method: POST
    path: "v1/report"
    metering:
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.10
      splits:
        - recipient: partner
          percent: 20
          memo: "Partner revenue share"
```

--------------------------------

### Run Debugger Inside Server

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Alternative method to start the Pay server with the debugger integrated. This allows debugging directly within the server process.

```sh
pay --sandbox server start provider.yml --debugger
```

--------------------------------

### Query x402 Endpoint for Fact

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Example command to query an x402 (Payment Required) endpoint for a fact using the 'pay' tool. This uses the sandbox environment.

```bash
pay --sandbox curl http://localhost:3402/x402/fact
```

--------------------------------

### Query MPP Endpoint for Quote

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Example command to query an MPP (Multi-Party Payment) endpoint for a quote using the 'pay' tool. This uses the sandbox environment.

```bash
pay --sandbox curl http://localhost:3402/mpp/quote/AAPL
```

--------------------------------

### Sign-message GET Request

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/message-signing-spec.md

Example of a GET request to the sign-message endpoint, used for retrieving information or initiating a signing process.

```APIDOC
## GET /solana-pay/sign-message

### Description
Initiates a message signing request or retrieves information related to message signing.

### Method
GET

### Endpoint
/solana-pay/sign-message

### Query Parameters
- **id** (string) - Optional - An identifier for the request.

### Request Example
```http
GET /solana-pay/sign-message?id=678910 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
```

### Response
#### Success Response (200)
- **label** (string) - The label associated with the request.
- **icon** (string) - The URL of an icon representing the request.

#### Response Example
```json
{
  "label": "Michael Vines",
  "icon": "https://example.com/icon.svg"
}
```
```

--------------------------------

### Run Bundled Solana Pay Demo

Source: https://context7.com/solana-foundation/pay/llms.txt

Execute the bundled demo for Solana Pay with sample payment endpoints.

```bash
pay server demo
```

--------------------------------

### Build and Test Pay from Source

Source: https://github.com/solana-foundation/pay/blob/main/README.md

Commands to build the release binary, run all tests, and perform linting using 'clippy' for the 'pay' project when building from source.

```sh
cd rust
just build   # release binary
just test    # all tests
just lint    # clippy (warnings = errors)
```

--------------------------------

### Create Wallet Client and Process Payment

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/core/OVERVIEW.md

Initialize a wallet client with a signer and use it to parse a payment URL, create transfer instructions, and send the transaction.

```typescript
import { createWalletClient } from '@solana/pay';

const wallet = createWalletClient({
    rpcUrl: 'https://api.mainnet-beta.solana.com',
    payer: walletSigner,
});

const parsed = wallet.pay.parseURL(url);
const instructions = await wallet.pay.createTransfer({ recipient, amount });
await wallet.sendTransaction(instructions);
```

--------------------------------

### Solana Pay CLI Basic Commands

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/setup-cli.md

A list of common Solana Pay CLI commands for setup, launching agents, making authorized HTTP requests, and managing skills and accounts. Use the `--sandbox` flag for ephemeral devnet wallets.

```sh
pay setup                         # create a wallet
```

```sh
pay claude                        # launch Claude Code with pay
```

```sh
pay codex                         # launch Codex with pay
```

```sh
pay curl <url>                    # HTTP request with user-authorized 402 handling
```

```sh
pay --sandbox curl <url>          # use an ephemeral devnet wallet
```

```sh
pay skills list                   # browse the API registry
```

```sh
pay skills endpoints <provider>   # list provider endpoints
```

```sh
pay account list                  # list accounts
```

```sh
pay topup                         # fund account
```

```sh
pay server start                  # run a payment gateway for your API
```

--------------------------------

### GET Response JSON Structure

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/SPEC.md

The expected JSON structure for a GET response from an application to a wallet, containing a label and an icon URL.

```json
{"label":"<label>","icon":"<icon>"}
```

--------------------------------

### Start Pay Gateway in Sandbox Mode

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/references/monetize-api.md

Initiate the Pay gateway server in sandbox mode for local testing. Ensure to use a non-debugger port for the server if the debugger is running separately.

```sh
EXAMPLE_API_KEY=... pay --sandbox server start provider.yml --bind 127.0.0.1:1403
```

--------------------------------

### GET Response Handling

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/SPEC.md

Details how wallets should handle GET requests, including expected JSON responses and display requirements for labels and icons.

```APIDOC
## GET Response

The wallet must handle HTTP client error, server error, and redirect responses. The application must respond with these, or with an HTTP `OK` JSON response with a body of
```json
{"label":"<label>","icon":"<icon>"}
```

The `<label>` value must be a UTF-8 string that describes the source of the transaction request. For example, this might be the name of a brand, store, application, or person making the request.

The `<icon>` value must be an absolute HTTP or HTTPS URL of an icon image. The file must be an SVG, PNG, or WebP image, or the wallet must reject it as **malformed**.

The wallet should not cache the response except as instructed by HTTP caching response headers.

The wallet should display the label and render the icon image to user.
```

--------------------------------

### Build Frontend and Compile Rust

Source: https://github.com/solana-foundation/pay/blob/main/pdb/README.md

Commands to build the frontend and compile the Rust binary for the Payment Debugger. Ensure the frontend is built before compiling Rust.

```bash
cd pdb && pnpm install --frozen-lockfile && pnpm build
cd ../rust && cargo build --release
```

--------------------------------

### GET Request for Sign-Message

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/message-signing-spec.md

A sample GET request to the sign-message endpoint. This is typically used to initiate the signing process or retrieve necessary information.

```http
GET /solana-pay/sign-message?id=678910 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
```

--------------------------------

### GET Request for Transaction Details

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/SPEC1.1.md

Wallets make a GET request to retrieve transaction details like label and icon from a merchant. The request should include Accept-Encoding and handle various HTTP responses.

```APIDOC
## GET Request

### Description

The wallet should make an HTTP `GET` JSON request to the URL. The request should not identify the wallet or the user. The wallet should make the request with an [Accept-Encoding header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding), and should respond with a [Content-Encoding header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) for HTTP compression. The wallet should display the domain of the URL as the request is being made.

### Response

#### Success Response (200)

The application must respond with an HTTP `OK` JSON response with a body of
```json
{"label":"<label>","icon":"<icon>"}
```

The `<label>` value must be a UTF-8 string that describes the source of the transaction request. The `<icon>` value must be an absolute HTTP or HTTPS URL of an icon image. The file must be an SVG, PNG, or WebP image, or the wallet must reject it as **malformed**.

The wallet should not cache the response except as instructed by [HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#controlling_caching) response headers.

The wallet should display the label and render the icon image to user.

#### Error Handling

The wallet must handle HTTP [client error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses), [server error](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses), and [redirect responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages).
```

--------------------------------

### GET Request Handler for Merchant Info

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/core/transaction-request/MERCHANT_INTEGRATION.md

Implement the GET request handler to provide merchant details like label and icon to the wallet. These details are displayed to the user during the transaction confirmation process.

```javascript
const get = async (request, response) => {
    const label = 'Exiled Apes Academy';
    const icon = 'https://exiledapes.academy/wp-content/uploads/2021/09/X_share.png';

    response.status(200).send({
        label,
        icon,
    });
};
```

--------------------------------

### Build and Test Rust CLI

Source: https://github.com/solana-foundation/pay/blob/main/CONTRIBUTING.md

Commands for building, linting, formatting, and testing the Rust CLI. Use `just rs run -- --help` to run the CLI with arguments.

```shell
just rs build              # Build release binary
```

```shell
just rs lint               # Clippy (warnings = errors)
```

```shell
just rs fmt               # Format check
```

```shell
just rs test               # Run all tests
```

```shell
just rs unit-test          # Unit tests only
```

```shell
just rs integration-test   # Integration tests only
```

```shell
just rs run -- --help      # Run the CLI
```

--------------------------------

### Sign-message PUT Request

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/message-signing-spec.md

Example of a PUT request to the sign-message endpoint, used to confirm a signed message.

```APIDOC
## PUT /solana-pay/sign-message

### Description
Confirms a previously signed message with the provided signature.

### Method
PUT

### Endpoint
/solana-pay/sign-message

### Query Parameters
- **id** (string) - Optional - An identifier for the request.

### Request Body
- **account** (string) - Required - The public key of the account that signed the message.
- **data** (string) - Required - The original message data that was signed.
- **state** (string) - Required - The state token received from the POST response.
- **signature** (string) - Required - The signature of the message.

### Request Example
```http
POST /solana-pay/sign-message?id=678910 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
Content-Type: application/json
Content-Length: 57

{
  "account": "mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN",
  "data": "SIGN_THIS_MESSAGE",
  "state": "eyJhbGciOiJIUzI1NiJ9.U0lHTl9USElTX01FU1NBR0U.KcZ1FnrT1ImAL-7LbALfZOx9F4I4LMuEE8_bg5Zmec4",
  "signature": "3ApozYFyp2ZxWuGvJS7Q1oV8M3YsLMV3WmwbjGCgktqXfdevjCZ92vA4F9V7Xj7KrN7JTtYStBSBeWnNN7vyHkg5"
}
```

### Response
#### Success Response (200)
An empty JSON object indicates a successful confirmation.

#### Response Example
```json
{}
```
```

--------------------------------

### Create Transfer Transaction Instructions

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/core/transfer-request/WALLET_INTEGRATION.md

Create transfer instructions from parsed URL parameters using the wallet client. This prepares the transaction for signing and sending.

```typescript
import { createWalletClient, type TransferRequestURL } from '@solana/pay';

const wallet = createWalletClient({
    rpcUrl: 'https://api.devnet.solana.com',
    payer: walletSigner,
});

const url =
    'solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?amount=0.01&reference=82ZJ7nbGpixjeDCmEhUcmwXYfvurzAgGdtSMuHnUgyny&label=Michael&message=Thanks%20for%20all%20the%20fish&memo=OrderId5678';
const { recipient, amount, splToken, reference, label, message, memo } = wallet.pay.parseURL(url) as TransferRequestURL;

/**
 * Create the transfer instructions from the parsed URL parameters
 */
const instructions = await wallet.pay.createTransfer({ recipient, amount: amount!, reference, memo });
```

--------------------------------

### Sign-message POST Request

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/message-signing-spec.md

Example of a POST request to the sign-message endpoint, used to submit a message for signing.

```APIDOC
## POST /solana-pay/sign-message

### Description
Submits a message to be signed by the user's wallet.

### Method
POST

### Endpoint
/solana-pay/sign-message

### Query Parameters
- **id** (string) - Optional - An identifier for the request.

### Request Body
- **account** (string) - Required - The public key of the account to sign with.

### Request Example
```http
POST /solana-pay/sign-message?id=678910 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
Content-Type: application/json
Content-Length: 57

{
  "account": "mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN"
}
```

### Response
#### Success Response (200)
- **message** (string) - The message to be signed by the user.
- **data** (string) - The data payload associated with the message.
- **state** (string) - A state token or identifier for the signing process.

#### Response Example
```json
{
  "message": "Sign the message to login",
  "data": "SIGN_THIS_MESSAGE",
  "state": "eyJhbGciOiJIUzI1NiJ9.U0lHTl9USElTX01FU1NBR0U.KcZ1FnrT1ImAL-7LbALfZOx9F4I4LMuEE8_bg5Zmec4"
}
```
```

--------------------------------

### GET /solana-pay

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/src/SPEC.md

Retrieves payment details or initiates a payment request. It requires an order ID as a query parameter.

```APIDOC
## GET /solana-pay

### Description
Retrieves payment details or initiates a payment request. It requires an order ID as a query parameter.

### Method
GET

### Endpoint
/solana-pay

### Parameters
#### Query Parameters
- **order** (string) - Required - The ID of the order.

### Request Example
```http
GET /solana-pay?order=12345 HTTP/1.1
Host: example.com
Connection: close
Accept: application/json
Accept-Encoding: br, gzip, deflate
```

### Response
#### Success Response (200)
- **label** (string) - The label for the payment.
- **icon** (string) - The URL of the icon associated with the payment.

#### Response Example
```json
{
  "label": "Michael Vines",
  "icon": "https://example.com/icon.svg"
}
```
```

--------------------------------

### Configure GNOME Keyring for Pay on Linux

Source: https://github.com/solana-foundation/pay/blob/main/README.md

On Linux, configure GNOME Keyring by copying a polkit policy file. This allows 'pay' to prompt for password or fingerprint before accessing the keypair.

```sh
sudo cp rust/config/polkit/sh.pay.unlock-keypair.policy /usr/share/polkit-1/actions/
```

--------------------------------

### Get Balance

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/SKILL.md

Checks the stablecoin balances in the Pay account. Useful before initiating paid work or when requested by the user.

```APIDOC
## get_balance

### Description
Check stablecoin balances before paid work or when asked.
```

--------------------------------

### Start Payment Debugger Server

Source: https://github.com/solana-foundation/pay/blob/main/README.md

Initiate a local gateway with the payment debugger to visualize 402 challenge-response cycles. This helps in understanding headers, protocols (MPP or x402), and identifying issues.

```sh
# Start a gateway with the debugger on any API spec
pay server start --debugger spec.yml

# Or run the bundled demo (sandbox + debugger + sample endpoints)
pay server demo
```

--------------------------------

### Get Catalog Entry

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/SKILL.md

Retrieves detailed information about a specific provider, including ready-to-call endpoint URLs and usage notes.

```APIDOC
## get_catalog_entry

### Description
Return ready-to-call endpoint URLs and usage notes for one provider.

### Parameters
#### Query Parameters
- **fqn** (string) - Required - The fully qualified name of the provider.
```

--------------------------------

### Build Static Website Content

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/docs/README.md

This command generates the static content for the website, which is placed in the `build` directory. The generated content can then be hosted using any static content hosting service.

```bash
$ npm run build
```

--------------------------------

### Access Free Health Endpoint

Source: https://github.com/solana-foundation/pay/blob/main/rust/example/README.md

Example command to access the free health endpoint of the server. No special flags or authentication are required.

```bash
curl http://localhost:3402/health
```

--------------------------------

### Kit Plugin Usage for Solana Pay

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/core/README.md

Compose Solana Pay functionalities with other @solana/kit plugins for a modular and controlled client setup.

```typescript
import { createEmptyClient } from '@solana/kit';
import { rpc, payerFromFile } from '@solana/kit-plugins';
import { solanaPayMerchant, solanaPayWallet } from '@solana/pay';

const client = await createEmptyClient()
  .use(rpc('https://api.devnet.solana.com'))
  .use(payerFromFile('~/.config/solana/id.json'))
  .use(solanaPayMerchant())
  .use(solanaPayWallet());

const url = client.pay.encodeURL({ recipient, amount: 1 });
const instructions = await client.pay.createTransfer({ recipient, amount: 1 });
```

--------------------------------

### Run Payment Debugger with Sandbox Server

Source: https://context7.com/solana-foundation/pay/llms.txt

Starts the payment debugger alongside any gateway using the 'pay' CLI. This tool visualizes payment flows as sequence diagrams for debugging 402 payment flows.

```shell
# Run the debugger alongside any gateway
pay --sandbox server start --debugger spec.yml
# Open http://localhost:1402/__pdb/
```

--------------------------------

### URL for 1 SOL Transfer Request with Redirect

Source: https://github.com/solana-foundation/pay/blob/main/typescript/packages/solana-pay/spec/SPEC1.1.md

Example of a Solana Pay URL for a 1 SOL transfer that includes a redirect URL.

```url
solana:mvines9iiHiQTysrwkJjGf2gb9Ex9jXJX8ns3qwf2kN?amount=1&label=Michael&message=Thanks%20for%20all%20the%20fish&memo=OrderId12345&redirect=https%3A%2F%2Fexample.com
```

--------------------------------

### Browse Available API Providers

Source: https://github.com/solana-foundation/pay/blob/main/skills/pay/SKILL.md

Use `list_catalog` to browse all available API providers. This is recommended for feasibility questions before answering if a task can be done via Pay.

```python
list_catalog()
```