### Setup Pay Environment

Source: https://pay.sh/docs/pay-for-apis/accounts

Initializes the pay environment, lists available accounts, and tops up the current account. Use this to get started with pay.

```sh
pay setup
pay account list
pay topup
```

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

### Install pay-kit Go Module

Source: https://pay.sh/docs/sdk/go

Install the pay-kit Go module using the go get command.

```bash
go get github.com/solana-foundation/pay-kit/go
```

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

### Install bun package

Source: https://pay.sh/docs/sdk/typescript

Install the @solana/pay-kit package using bun.

```bash
bun add @solana/pay-kit
```

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

### Start a Sandbox Gateway

Source: https://pay.sh/docs/accept-payments

Use this command to start a demo sandbox gateway. It's recommended to begin with a sandbox environment before moving to production.

```sh
pay --sandbox server demo
```

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

### Install npm package

Source: https://pay.sh/docs/sdk/typescript

Install the @solana/pay-kit package using npm.

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

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

### Install pay CLI with Homebrew

Source: https://pay.sh/docs/sdk/typescript

Install the 'pay' command-line interface tool using Homebrew.

```bash
brew install pay
```

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

### Start Gateway Provider with Debugger

Source: https://pay.sh/docs/protocol/troubleshooting

Start a gateway provider in a sandbox environment with the debugger enabled for payment loops.

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

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

### Start server with OpenAPI

Source: https://pay.sh/docs/accept-payments/openapi

Starts the payment server, serving the OpenAPI specification from `openapi.json`.

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

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

### Start local `pay server demo`

Source: https://pay.sh/docs/toolchain/commands/developers

Starts a local demo of the pay server with a dashboard for tracing payments. Uses bundled endpoints and does not require a provider spec.

```sh
pay --sandbox server demo
```

```sh
pay --sandbox server demo --local
```

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

### Start Provider Server

Source: https://pay.sh/docs/accept-payments/provider-spec

Command to start the Pay server with a specified provider spec file. Use --sandbox for testing.

```sh
pay --sandbox server start provider.yml --bind 127.0.0.1:1402
```

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

### Start Sandbox Server

Source: https://pay.sh/docs/building-with-pay/yaml-specification

Command to start the Pay.sh sandbox server using the starter YAML specification.

```sh
pay --sandbox server start starter.yml

```

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

### Install pnpm package

Source: https://pay.sh/docs/sdk/typescript

Install the @solana/pay-kit package using pnpm.

```bash
pnpm add @solana/pay-kit
```

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

### Starting Pay Server with Session Config

Source: https://pay.sh/docs/building-with-pay/payment-channels/sessions

Start the pay server using the specified provider configuration file. This command assumes a sandbox environment.

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

```

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

### Start Local Sandbox Server

Source: https://pay.sh/docs-assets/subscriptions/tiers.yml

Starts the local sandbox server for the tiered subscription configuration. This command publishes the defined tiers on the first launch.

```bash
pay --sandbox server start tiers.yml
```

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

### Start Pay Server with CLI

Source: https://pay.sh/docs/sdk

Use the `pay` CLI to start a gateway by pointing it to a provider YAML file. This is suitable for gating existing APIs or when payment logic should not be in the application code.

```sh
pay server start provider.yml
```

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

### Install and Verify Pay

Source: https://pay.sh/docs/get-started

Install the Pay CLI using Homebrew and check its version. This is the first step before running any Pay commands.

```shell
brew install pay
pay --version
```

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

### Account Configuration Example

Source: https://pay.sh/docs/toolchain/configuration

Example of the accounts.yml file structure for managing wallets grouped by network. This file is mandatory for non-ephemeral wallets.

```yaml
version: 2
accounts:
  mainnet:
    default:
      keystore: apple-keychain # apple-keychain | gnome-keyring | windows-hello | file | ephemeral
      active: true # used when multiple accounts share a network
      auth_required: true # mainnet defaults to true; sandbox defaults to false
      pubkey: 96WoyH3JmANSMsQLGC3MKyiGiXCymZyM9SLaWjcRrKuD
  localnet:
    sandbox-abc123:
      keystore: ephemeral
      pubkey: 5jSk… # base58
      secret_key_b58: 4xZ… # only for keystore: ephemeral
      created_at: 2026-05-02T17:21:03Z

```

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

### CLI: Install pay CLI

Source: https://pay.sh/docs/sdk/go

Install the 'pay' CLI tool using Homebrew or npm. This tool acts as a client for any 402-gated route.

```bash
brew install pay     # or: npm install -g @solana/pay
```

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

### Install solana-pay-kit with Flask support

Source: https://pay.sh/docs/sdk/python

Install the solana-pay-kit package with optional extras for Flask. Other options include [fastapi] or [django].

```bash
pip install "solana-pay-kit[flask]"   # or [fastapi] / [django]
```

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

### Install and Run Pay CLI in Sandbox

Source: https://pay.sh/docs/toolchain

Installs the pay CLI using Homebrew and demonstrates a basic command execution in a sandbox environment. The sandbox flag routes to a hosted cluster and auto-funds an ephemeral wallet for simulated payments.

```sh
brew install pay
pay --sandbox curl https://debugger.pay.sh/mpp/quote/AAPL
```

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

### Start Pay Sandbox Server

Source: https://pay.sh/docs/building-with-pay/subscriptions/yaml-specification

Starts the Pay sandbox server with a specified provider YAML file. This command handles the creation and on-chain publishing of subscription plans if they do not already exist.

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

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

### Metered Usage Server Example

Source: https://pay.sh/docs/sdk/go/schemes

Server-side implementation for a metered usage payment scheme. This example demonstrates authorizing a ceiling, metering actual usage, and settling the real amount.

```go
package main

import (
	"context"
	"log"
	"net/http"

	"github.com/paypay3/paykit-go/paykit"
	"github.com/paypay3/paykit-go/paykit/gate"
	"github.com/paypay3/paykit-go/paykit/gate/middleware"
)

func main() {
	// GateUsage gate advertises Amount as the ceiling
	gate := gate.NewUsage(
		gate.WithAmount(paykit.MustAmount("5000")))

	// Middleware to require usage-based payment
	client := middleware.RequireUsage(gate)

	http.Handle("/summarize", client(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Meter actual usage and report it
		// For example, count tokens or bytes processed
		actualUsage := paykit.MustAmount("3500") // Example: 3500 tokens
		paykit.ChargeFrom(r.Context()).SetAmount(actualUsage)

		log.Println("Usage metered, handler running")
		w.WriteHeader(http.StatusOK)
	})))

	log.Println("Server listening on :8080")
	http.ListenAndServe(":8080", nil)
}

```

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

### Start pay server with a provider spec

Source: https://pay.sh/docs/accept-payments/deploy

Use this command to start the pay server in a production environment, specifying the provider configuration file and the bind address.

```sh
pay server start provider.yml --bind 0.0.0.0:8080
```

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

### Fixed Charge Server Example

Source: https://pay.sh/docs/sdk/go/schemes

Server-side implementation for a fixed charge payment scheme. This example demonstrates how to set up a gate that charges a fixed amount before the handler runs.

```go
package main

import (
	"context"
	"log"
	"net/http"

	"github.com/paypay3/paykit-go/paykit"
	"github.com/paypay3/paykit-go/paykit/gate"
	"github.com/paypay3/paykit-go/paykit/gate/middleware"
)

func main() {
	// Default gate: GateFixed
	gate := gate.NewFixed(
		gate.WithAmount(paykit.MustAmount("1000")))

	// Middleware to require payment
	client := middleware.Require(gate)

	http.Handle("/quote", client(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		log.Println("Payment successful, handler running")
		w.WriteHeader(http.StatusOK)
	})))

	log.Println("Server listening on :8080")
	http.ListenAndServe(":8080", nil)
}

```

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

### Setup a New Account

Source: https://pay.sh/docs/toolchain/commands/accounts

Generates a new keypair, stores it securely, and configures agent integrations. Use `--force` to replace an existing account.

```sh
pay setup
```

```sh
pay setup --force                       # replace an existing account
```

```sh
pay setup --backend keychain            # macOS (default)
```

```sh
pay setup --backend gnome-keyring       # Linux (default)
```

```sh
pay setup --backend windows-hello       # Windows (default)
```

```sh
pay setup --update                      # refresh MCP config only — no new account
```

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

### Install pay CLI from source

Source: https://pay.sh/docs/get-started/install

Build and install the pay CLI from its source code repository. This method is for developers or users who need the latest changes.

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

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

### Start Sandbox Gateway with Debugger

Source: https://pay.sh/docs/accept-payments/gateway-overview

Starts a local sandbox gateway with the debugger enabled. Useful for development and testing.

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

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

### Run Monthly Subscription Locally

Source: https://pay.sh/docs-assets/subscriptions/monthly.yml

Use this command to start the local server for the monthly subscription service.

```bash
pay --sandbox server start monthly.yml
```

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

### Initialize wallet and agent configuration

Source: https://pay.sh/docs/get-started/install

Set up a new pay wallet in the OS secure store and install the MCP configuration for detected agents. This is the first step for using pay.

```sh
pay setup
pay topup
```

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

### Verify Pay CLI Installation and Account

Source: https://pay.sh/docs/toolchain/install

Verify the Pay CLI installation by checking the version and confirm your mainnet account status and stablecoin balances using `pay whoami`.

```sh
pay --version
pay whoami
```

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

### Start sandbox server and test endpoint

Source: https://pay.sh/docs/accept-payments/per-request

Start the Pay sandbox server and then use curl to test a per-request endpoint. Ensure the server is running before sending requests.

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

```sh
pay --sandbox curl http://127.0.0.1:1402/v1/generate -d '{"prompt":"test"}'
```

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

### Start Gateway with Provider Spec

Source: https://pay.sh/docs/accept-payments/gateway-overview

Loads a provider spec and starts an HTTP gateway. This is the primary command for running the pay gateway.

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

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

### Start Embedded Debugger

Source: https://pay.sh/docs/accept-payments/debugging

Start the server with the embedded debugger enabled. Use this to inspect payment flows directly.

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

```sh
pay --sandbox curl http://127.0.0.1:1402/v1/search -d '{"query":"test"}'
```

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

### Fixed Charge Client Example

Source: https://pay.sh/docs/sdk/go/schemes

Client-side implementation for initiating a fixed charge payment. This example shows a single call through the paying transport to settle a fixed amount.

```go
package main

import (
	"context"
	"log"
	"net/http"

	"github.com/paypay3/paykit-go/paykit"
	"github.com/paypay3/paykit-go/paykit/client"
)

func main() {
	// Use the client to make a payment request
	payClient := client.New(
		client.WithTransport(client.NewHTTPTransport("http://localhost:8080", "/quote", http.DefaultClient)))

	ctx := context.Background()
	amount := paykit.MustAmount("1000")

	resp, err := payClient.Charge(ctx, amount)
	if err != nil {
		log.Fatalf("Charge failed: %v", err)
	}

	log.Printf("Charge successful: %+v\n", resp)
}

```

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

### Install pay CLI globally with npm

Source: https://pay.sh/docs/get-started/install

Install the pay CLI globally using npm. This method allows for system-wide access to the pay commands.

```sh
npm install -g @solana/pay
pay --version
```

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

### Start Local Pay Gateway

Source: https://pay.sh/docs/building-with-pay/getting-started

Run a local pay gateway with a bundled spec. This command writes 'pay-demo.yaml' and binds to '127.0.0.1:1402'.

```sh
pay --sandbox server demo
```

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

### Add a provider source with pay install

Source: https://pay.sh/docs/toolchain/commands/other

Use `pay install` as a shorthand to add a provider source, typically from a GitHub repository. This command is an alias for `pay skills add`.

```sh
pay install solana-foundation/pay-skills
```

```sh
pay -i solana-foundation/pay-skills
```

```sh
pay add solana-foundation/pay-skills
```

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

### Install a Provider Source

Source: https://pay.sh/docs/using-pay/skills

Registers a local or custom skills.json source for the Pay.sh CLI. This allows `pay skills search` to query custom sources.

```sh
pay install your-org/your-repo
```

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

### Run Pay Server Locally

Source: https://pay.sh/docs-assets/subscriptions/annual-with-expiry.yml

Command to start the pay server locally with the annual-with-expiry configuration file in sandbox mode.

```bash
pay --sandbox server start annual-with-expiry.yml
```

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

### Run the Flask application

Source: https://pay.sh/docs/sdk/python

Execute the Python script to start the Flask development server.

```bash
python app.py
```

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

### Start Pay Server Sandbox

Source: https://pay.sh/docs/building-with-pay/subscriptions/examples

Run a downloaded subscription spec locally in the Pay Server sandbox. The first launch publishes the on-chain Plan PDA.

```sh
pay --sandbox server start <file>.yml
```

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

### Start Pay Server Proxy

Source: https://pay.sh/docs/toolchain/commands/developers

Starts a proxy that gates your API with stablecoin payments. Reads endpoint pricing and payment requirements from a YAML spec. Use `--sandbox` for testing.

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

```sh
pay server start provider.yml --bind 0.0.0.0:8080
```

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

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

### Initiate a Charge via Client

Source: https://pay.sh/docs/sdk/rust/client

Example of initiating a charge by making a request to a quote URL using the client.

```rust
<Snippet lang="rust" name="charge.client" url="https://api.example.com/quote" />
```

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

### Import necessary modules for x402 client

Source: https://pay.sh/docs/sdk/python/client

Import the Signer class and the x402_async_client function from the solana_pay_kit library. This is the initial setup for using the auto-pay client.

```python
from solana_pay_kit import Signer
from solana_pay_kit.protocols.x402.client import SolanaRpc, x402_async_client
```

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

### Use CLI to interact with pay-kit server

Source: https://pay.sh/docs/sdk/python/client

Example of using the 'pay' CLI tool to make a request to a local pay-kit server. This is a simpler alternative for most use cases.

```bash
pay curl http://127.0.0.1:8000/quote
```

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

### Start Local MCP Server

Source: https://pay.sh/docs/toolchain/commands/agents

Use this command to start the local Model Context Protocol server. This server is required for MCP-capable clients like Claude Code and Cursor.

```sh
pay mcp
```

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

### Per-Request Pricing Example

Source: https://pay.sh/docs/building-with-pay/pricing

Configures pricing for a POST endpoint, charging a fixed rate per request.

```yaml
endpoints:
  - method: POST
    path: 'v1/search'
    description: 'Search records by keyword.'
    metering:
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.01
```

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

### Pay CLI Global Flags Example

Source: https://pay.sh/docs/toolchain/commands

Demonstrates how to use global flags like --sandbox, --account, and --no-dna with Pay CLI commands.

```sh
pay --sandbox curl <url>
pay --account work send 1 <recipient>
pay --no-dna --mainnet whoami
```

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

### Provider Directory Structure Example

Source: https://pay.sh/docs/using-pay/skills

Illustrates the directory layout for provider definitions within the pay-skills registry. The path reflects the provider's fully-qualified name (FQN).

```bash
providers/
  quicknode/rpc/PAY.md                       
  paysponge/2captcha/PAY.md                  
  merit-systems/stableenrich/enrichment/PAY.md
  solana-foundation/google/translate/PAY.md
```

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

### Calling Metered and Subscription Endpoints

Source: https://pay.sh/docs/building-with-pay/subscriptions/examples

Examples of how to call metered and subscription endpoints using the 'pay' command. The first call is per-call pricing, and the second is a flat-fee subscription.

```sh
# Per-call: pays $0.01 every time.
pay --sandbox curl http://127.0.0.1:1402/api/v1/quote/AAPL

# Flat-fee: pays $9.99 once, free for 30 days.
pay --sandbox curl http://127.0.0.1:1402/api/v1/pro/quote/AAPL

```

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

### Initialize x402 Client

Source: https://pay.sh/docs/sdk/go/client

Use `x402client.NewClient` to create an `*http.Client` that handles x402 exact payments. Ensure you have the necessary import.

```go
import x402client "github.com/solana-foundation/pay-kit/go/protocols/x402/client"
```

```go
client := x402client.NewClient(signer, "https://api.example.com/quote")
```

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

### Start Pay Server on a Different Port

Source: https://pay.sh/docs/toolchain/troubleshooting

If port 1402 is in use, you can bind the pay server to a different port, for example, 1403, by specifying the --bind flag.

```sh
pay server start spec.yml --bind 0.0.0.0:1403
```

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

### Directory Layout Examples

Source: https://pay.sh/docs/accept-payments/publish-to-pay-skills

Illustrates the directory structure for provider entries in the registry. The two-level layout is for direct API operation, while the three-level layout is for gateways proxying other providers.

```txt
providers/
  <operator>/<name>/PAY.md              # FQN: <operator>/<name>
  <operator>/<origin>/<name>/PAY.md     # FQN: <operator>/<origin>/<name>
```

```txt
providers/acme/search/
  PAY.md
  openapi.json
```

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

### Configure and gate a route in Flask

Source: https://pay.sh/docs/sdk/python

Set up the solana-pay-kit configuration and use the require_payment decorator to gate a Flask route. This example imports necessary components and defines a basic route.

```python
import solana_pay_kit
from flask import Flask, jsonify
from solana_pay_kit import Gate, usd
from solana_pay_kit.flask import payment, require_payment
```

```python
solana_pay_kit.configure(
    operator=Gate(
        signer=Signer.from_key("demo.json"),
        currency=usd
    )
)

app = Flask(__name__)

@app.route("/quote")
@require_payment(gate=True)
def quote():
    return jsonify({"message": "Payment successful!"})

if __name__ == "__main__":
    app.run(port=8000)
```

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

### Fixed Charge Client Example

Source: https://pay.sh/docs/sdk/rust/schemes

This Rust code snippet illustrates a client-side implementation for a fixed charge payment scheme. It shows how a client would interact with a server to pay a challenge.

```rust
use solana_pay_kit::client::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("https://api.example.com/quote");
    let response = client.charge_fixed("user_id", 1000).await?;
    println!("Payment response: {:?}", response);
    Ok(())
}
```

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

### Get Daily Market Brief

Source: https://pay.sh/docs-assets/subscriptions/weekly.yml

Retrieves the daily market brief for subscribers of the weekly plan. This endpoint is accessible via a GET request.

```APIDOC
## GET api/v1/daily-brief

### Description
Daily market brief — weekly subscription.

### Method
GET

### Endpoint
api/v1/daily-brief

### Subscription Details
- **Period**: 1 week
- **Price**: $1.99 USDC
```

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

### Server: Create PayKit Client

Source: https://pay.sh/docs/sdk/go

Create a paykit client by initializing it with a Config. The Config includes the network, accepted protocols, and MPP realm/challenge-binding secret. If no Operator.Signer is provided, it defaults to an in-memory demo signer and the Surfpool sandbox for local testing.

```go
import (
    "fmt"
    "net/http"

    "github.com/solana-foundation/pay-kit/go/paykit"
    _ "github.com/solana-foundation/pay-kit/go/paycore/signer"
    _ "github.com/solana-foundation/pay-kit/go/paykit/adapters/mpp"
    _ "github.com/solana-foundation/pay-kit/go/paykit/adapters/x402"
)

func main() {
    client, err := paykit.New(paykit.Config{
        Network: paykit.NetworkSandbox,
        Accept: []paykit.Protocol{
            paykit.ProtocolX402,
            paykit.ProtocolMPP,
        },
        MPP: paykit.MPPConfig{
            Realm: "my-realm",
            ChallengeBindingSecret: "my-secret",
        },
        // Operator: paykit.OperatorConfig{
        //  Signer: &mySigner{}, // Use your own signer
        // },
    })
    if err != nil {
        panic(err)
    }

    http.HandleFunc("/quote", func(w http.ResponseWriter, r *http.Request) {
        payment, err := paykit.PaymentFrom(r.Context())
        if err != nil {
            // Handle error: payment not found or invalid
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        fmt.Fprintf(w, "Payment received: %s", payment.ID)
    })

    // Wrap the handler with client.Require to gate the route
    http.Handle("/quote", client.Require(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        payment, err := paykit.PaymentFrom(r.Context())
        if err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
            return
        }
        fmt.Fprintf(w, "Payment processed for ID: %s", payment.ID)
    })))

    fmt.Println("Server listening on :4567")
    http.ListenAndServe(":4567", nil)
}
```

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

### Start Debugger Proxy

Source: https://pay.sh/docs/accept-payments/debugging

Start the debugger proxy to inspect payment flows. Ensure the gateway is unbound from port 1402 when using this proxy. Use this to test with curl.

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

```sh
pay --sandbox --debugger curl http://127.0.0.1:1403/v1/search -d '{"query":"test"}'
```

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

### Create a Basic PayKit Client

Source: https://pay.sh/docs/sdk/typescript/client

Demonstrates how to initialize the createPayKitClient for making payment-aware fetch requests. This client automatically handles 402 challenges and payment retries.

```typescript
const client = createPayKitClient({
  signer: createKeyPairSignerFromBytes(new Uint8Array([])),
  rpcUrl: "https://api.example.com/api/v1/quote/AAPL",
});

// Use client.fetch like the standard fetch API
client.fetch("https://api.example.com/api/v1/quote/AAPL").then(response => {
  // Handle response
});
```

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

### Run pay CLI command via npx without global install

Source: https://pay.sh/docs/get-started/install

Execute any pay command using npx without a system-wide installation. This is useful for one-shot calls or testing.

```sh
npx @solana/pay --sandbox curl https://debugger.pay.sh/mpp/quote/AAPL
npx @solana/pay claude "buy me some flowers"
```

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

### Start Debugging Agent Sessions with Pay

Source: https://pay.sh/docs/using-pay/pass-through-commands

Start a debugging session for an agent using `pay --sandbox --debugger claude`. This is useful for inspecting the payment exchange during agent interactions.

```sh
pay --sandbox --debugger claude
```

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

### Load Signer from Local Key Material

Source: https://pay.sh/docs/sdk/go/signers

Demonstrates how to create a paykit.Signer from different local key formats: Solana CLI JSON file, environment variable, or raw byte array.

```go
import "github.com/solana-foundation/pay-kit/go/paycore/signer"

s, err := signer.FromFile("operator.json") // Solana CLI JSON keypair
s, err := signer.FromEnv("OPERATOR_KEY")   // JSON / hex / base58, auto-detected
s, err := signer.FromBytes(secretKeyBytes) // 64-byte keypair
```

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

### Initialize x402 async client for payments

Source: https://pay.sh/docs/sdk/python

Create an httpx.AsyncClient that automatically handles x402 payments by retrying requests with a signed PAYMENT-SIGNATURE header when a 402 response is received.

```python
from solana_pay_kit import Signer
from solana_pay_kit.protocols.x402.client import SolanaRpc, x402_async_client

async def main():
    async with x402_async_client(
        url="https://api.example.com/quote",
        signer=Signer.from_key("demo.json"),
        rpc=SolanaRpc(url="http://127.0.0.1:8899")
    ) as client:
        response = await client.get("/quote")
        print(response.text)

import asyncio
asyncio.run(main())
```

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

### Use CLI for Payments

Source: https://pay.sh/docs/sdk/go/client

For most scenarios, the `pay` CLI is the easiest way to handle wallet interactions, signing, and 402 retries against a pay-kit server.

```bash
pay curl http://127.0.0.1:4567/quote
```

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

### Fixed Charge Client

Source: https://pay.sh/docs/sdk/python/schemes

Client-side implementation for settling a fixed charge payment. This example interacts with the '/quote' endpoint.

```python
from solana_pay_kit.client import Client

client = Client()

# Example of how to make a payment
# client.pay("https://api.example.com/quote", amount=1000, recipient="recipient_address")
```

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

### Create a New Account with Specific Backend and Force Option

Source: https://pay.sh/docs/using-pay/manage-accounts

Create a new account, specifying the backend for secret key storage (e.g., `keychain`) and using `--force` to overwrite an existing account with the same name.

```sh
pay account new trading --backend keychain --force
```

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

### Get Enterprise Stock Quote

Source: https://pay.sh/docs-assets/subscriptions/tiers.yml

Retrieves enterprise stock quotes for a given symbol. This tier is priced at $199/month.

```APIDOC
## GET api/v1/enterprise/quote/{symbol}

### Description
Retrieves enterprise stock quotes for a given symbol. This tier is priced at $199/month.

### Method
GET

### Endpoint
/api/v1/enterprise/quote/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The stock symbol to get a quote for.

### Response
#### Success Response (200)
- **quote** (object) - Description of the quote details.

#### Response Example
{
  "quote": {
    "symbol": "AAPL",
    "price": 170.50,
    "timestamp": "2023-10-27T10:00:00Z",
    "advanced_data": "some_enterprise_data",
    "analytics": "detailed_analytics"
  }
}
```

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

### Get Pro Stock Quote

Source: https://pay.sh/docs-assets/subscriptions/tiers.yml

Retrieves pro stock quotes for a given symbol. This tier is priced at $25/month.

```APIDOC
## GET api/v1/pro/quote/{symbol}

### Description
Retrieves pro stock quotes for a given symbol. This tier is priced at $25/month.

### Method
GET

### Endpoint
/api/v1/pro/quote/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The stock symbol to get a quote for.

### Response
#### Success Response (200)
- **quote** (object) - Description of the quote details.

#### Response Example
{
  "quote": {
    "symbol": "AAPL",
    "price": 170.50,
    "timestamp": "2023-10-27T10:00:00Z",
    "advanced_data": "some_pro_data"
  }
}
```

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

### Build x402 payment header and parse challenge

Source: https://pay.sh/docs/sdk/python/client

Demonstrates the low-level building blocks for manually constructing payment headers and parsing x402 challenges. Use these if you are managing your own HTTP requests.

```python
from solana_pay_kit.protocols.x402.client import build_payment_header, parse_x402_challenge

offer = parse_x402_challenge(headers, body, selection)        # select an offer
header = await build_payment_header(signer, rpc, offer)        # base64 PAYMENT-SIGNATURE
```

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

### Get Basic Stock Quote

Source: https://pay.sh/docs-assets/subscriptions/tiers.yml

Retrieves basic stock quotes for a given symbol. This tier is priced at $5/month.

```APIDOC
## GET api/v1/basic/quote/{symbol}

### Description
Retrieves basic stock quotes for a given symbol. This tier is priced at $5/month.

### Method
GET

### Endpoint
/api/v1/basic/quote/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The stock symbol to get a quote for.

### Response
#### Success Response (200)
- **quote** (object) - Description of the quote details.

#### Response Example
{
  "quote": {
    "symbol": "AAPL",
    "price": 170.50,
    "timestamp": "2023-10-27T10:00:00Z"
  }
}
```

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

### Override public URL for OpenAPI

Source: https://pay.sh/docs/accept-payments/openapi

Starts the payment server, serving the OpenAPI specification from `openapi.json` and overriding the public URL to `https://gateway.example.com`.

```sh
pay server start provider.yml \
  --openapi openapi.json \
  --public-url https://gateway.example.com
```

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

### Proxy Routing with Path Rewrites

Source: https://pay.sh/docs-assets/provider.schema.json

Example of proxy routing with path rewrites, where path segments are dynamically prepended based on environment variables.

```yaml
routing:
  type: proxy
  url: https://translation.googleapis.com/
  path_rewrites:
    - prefix: "v3/projects/{projectId}"
      env: GOOGLE_PROJECT_ID
```

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

### Weekly Content Access

Source: https://pay.sh/docs/building-with-pay/subscriptions/examples

This example shows how to set up a weekly subscription for content access at $1.99 per week using USDC. The merchant's renewal worker will pull the payment every 7 days until cancellation.

```APIDOC
## GET api/v1/daily-brief

### Description
Provides daily brief content on a weekly subscription basis.

### Method
GET

### Endpoint
/api/v1/daily-brief

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```sh
pay --sandbox curl http://127.0.0.1:1402/api/v1/daily-brief
```

### Response
#### Success Response (200)
- **content** (string) - The daily brief content.

#### Response Example
{
  "content": "Daily news summary..."
}
```

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

### Proxy Routing with Header Authentication

Source: https://pay.sh/docs/accept-payments/provider-spec

Example of configuring proxy routing with header authentication. The API token is securely injected from an environment variable.

```yaml
routing:
  type: proxy
  url: https://api.example.com/
  auth:
    method: header
    key: 'authorization'
    prefix: 'Bearer '
    value_from_env: EXAMPLE_API_TOKEN
```

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

### Get Subscription Status

Source: https://pay.sh/docs/building-with-pay/subscriptions/examples

Retrieves detailed status information for a specific subscription using its ID. Essential for diagnosing issues or verifying state.

```sh
pay subscriptions status BXQGmO5VwTrl5RfFr6Y8XQZ4nPj9QqMOiKkRn3pZ4ZE
```

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

### Start Agent Sessions with Pay

Source: https://pay.sh/docs/using-pay/pass-through-commands

Initiate agent sessions using `pay --sandbox claude` or `pay --sandbox codex`. These commands attach Pay MCP tools, enabling the agent to discover and call paid APIs.

```sh
pay --sandbox claude
```

```sh
pay --sandbox codex
```

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

### Launch Sandbox Agents

Source: https://pay.sh/docs/pay-for-apis/agents

Use these commands to start the Claude or Codex agent in a sandbox environment. This ensures that no real transactions are made during initial testing.

```sh
pay --sandbox claude

```

```sh
pay --sandbox codex

```

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

### PAY.md Frontmatter Example

Source: https://pay.sh/docs/using-pay/skills

Shows a typical frontmatter structure for a PAY.md file, containing metadata used by AI agents for provider discovery and selection.

```yaml
---
name: rpc
title: 'Quicknode'
description: 'Pay-per-request JSON-RPC endpoints for 140+ blockchain networks…'
use_case: 'Use for blockchain JSON-RPC, querying account or contract state…'
category: compute
service_url: https://x402.quicknode.com
openapi:
  path: openapi.json
---

```

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

### Handling PayKit Initialization Errors

Source: https://pay.sh/docs/sdk/rust/errors

Demonstrates how to handle potential errors returned by PayKit::new during initialization. It specifically catches and panics on MPP or x402 configuration rejections.

```rust
let pay = match PayKit::new(config) {
    Ok(pay) => pay,
    Err(PayKitError::Mpp(msg)) => panic!("MPP config rejected: {msg}"),
    Err(PayKitError::X402(msg)) => panic!("x402 config rejected: {msg}"),
};
```