@valeo/pay

Pay for any API with Solana tokens. One function call.

Install

npm install @valeo/pay @solana/web3.js @solana/spl-token

Quick Start

import { createValeoClient } from "@valeo/pay";
import { Keypair } from "@solana/web3.js";

const client = createValeoClient({
  keypair: Keypair.fromSecretKey(/* your key */),
  rpcUrl: "https://api.mainnet-beta.solana.com",
});

const response = await client.paidFetch("https://pay.valeo.so/e/abc123/weather");
const data = await response.json();

How It Works

Agent                           Valeo Gateway                  Solana
  |                                  |                            |
  |  GET /e/abc123/weather           |                            |
  |--------------------------------->|                            |
  |                                  |                            |
  |  402 Payment Required            |                            |
  |  { accepts: [BONK, USDC, ...] }  |                            |
  |<---------------------------------|                            |
  |                                  |                            |
  |  SPL token transfer              |                            |
  |---------------------------------------------------------->   |
  |  tx signature                    |                            |
  |<----------------------------------------------------------   |
  |                                  |                            |
  |  GET /e/abc123/weather           |                            |
  |  X-PAYMENT: { txSignature }      |                            |
  |--------------------------------->|                            |
  |                                  |  verify on-chain           |
  |                                  |--------------------------->|
  |                                  |                            |
  |  200 OK + receipt                |                            |
  |<---------------------------------|                            |

paidFetch() handles all of this automatically.

Usage

For AI Agents (keypair signing)

import { createValeoClient } from "@valeo/pay";
import { Keypair } from "@solana/web3.js";
import bs58 from "bs58";

const client = createValeoClient({
  keypair: Keypair.fromSecretKey(bs58.decode(process.env.SOLANA_PRIVATE_KEY!)),
  rpcUrl: "https://api.mainnet-beta.solana.com",
});

const response = await client.paidFetch("https://pay.valeo.so/e/abc123/weather");
const data = await response.json();

With Options (power users)

const response = await client.paidFetch("https://pay.valeo.so/e/abc123/weather", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ city: "Berlin" }),

  preferredToken: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",  // pay with BONK
  maxPrice: 1000000,
  commitment: "confirmed",
  onPayment: (info) => {
    console.log(`Paid ${info.amount} ${info.token} — tx: ${info.txSignature}`);
  },
});

Browser Wallet Adapter

import { createValeoClient } from "@valeo/pay";

const client = createValeoClient({
  walletAddress: publicKey.toBase58(),
  signTransaction: wallet.signTransaction,
  rpcUrl: "https://api.mainnet-beta.solana.com",
});

const response = await client.paidFetch("https://pay.valeo.so/e/abc123/weather");

API Reference

createValeoClient(config)

| Option | Type | Description | |--------|------|-------------| | keypair | Keypair | Solana keypair for automatic signing | | walletAddress | string | Wallet public key (with signTransaction) | | signTransaction | function | External signer from wallet adapter | | rpcUrl | string | Solana RPC endpoint URL | | commitment | "confirmed" \| "finalized" | Default commitment level | | defaultPreferredToken | string | Default token mint to prefer | | defaultMaxPrice | number | Default max raw amount |

paidFetch(url, options?)

Extends standard fetch options with:

| Option | Type | Description | |--------|------|-------------| | preferredToken | string | Prefer this token mint | | maxPrice | number | Reject if all options exceed this | | commitment | "confirmed" \| "finalized" | Override commitment | | onPayment | (info: PaymentInfo) => void | Callback after payment sent | | onPricing | (options: TokenPaymentOption[]) => void | Callback when 402 received |

Returns Response with an optional .receipt property containing the gateway's cryptographic receipt.

discoverPricing(response)

Parse a 402 Response into PaymentRequired | null.

selectToken(accepts, preferredMint?, maxPrice?)

Select the best token from payment options. Priority: preferred > USDC > first available.

License

MIT