Solana Pay

Developers can use transaction requests to implement several advanced payment and engagement patterns:

• Atomic Multi-Action Transactions: Merchants can mint NFTs or transfer loyalty tokens simultaneously with the payment at the point of sale.
• Composable DeFi at POS: Enable complex transactions involving swaps, borrowing, escrow, or yield generation during a purchase. This can support features like refunds, chargebacks, or buy-now-pay-later.
• Reduced User Friction: Merchants can pay for transaction fees, token account creation, or NFT minting on behalf of the customer, allowing users to transact without needing SOL in their wallets.
• Permissioned Payments: Merchants can decline to respond to a request, which can be used to enforce authentication or compliance requirements.
• Dynamic Brand Experiences: Beyond simple commerce, brands can use requests to send tokens, invitations, or gifts to customers (e.g., minting 1:1 NFTs for event attendees).

To ensure efficient and cost-effective use of Pay providers, follow these rules:

Provider Selection Rules

• Hard-filter mismatches: Do not pay if there is a wrong network, wrong currency, unusable endpoint shape, incompatible method/body, or if the price exceeds the user's limit.
• Prefer exact task ownership:
  • Influencer search $\rightarrow$ social data or influencer provider.
  • Wallet balances/history $\rightarrow$ blockchain analytics.
  • Stablecoin/token volume $\rightarrow$ blockchain analytics or BigQuery.
  • Raw Solana RPC $\rightarrow$ RPC provider.
  • Image/video generation $\rightarrow$ media generation.
  • SQL over public datasets $\rightarrow$ BigQuery.
• Tie-breaking: If multiple providers match, resolve ties in this order: exact endpoint fit, supported network/currency, usable request shape, likely result quality/freshness, and total estimated price.
• Endpoint Type: Prefer simple synchronous endpoints for small one-shot tasks. Use async or batch endpoints only if they materially reduce cost or are required by the task.
• Uncertainty: If price, schema, network support, or quality is unclear after running search_catalog and get_catalog_entry, ask the user instead of guessing.
• Failure Handling: If a paid call fails with 404, unsupported network, invalid payment challenge, or unusable schema, do not retry random providers. Try at most one clear fallback or ask the user.

Cost Optimization Patterns

• Check usage notes: Use provider usage notes from get_catalog_entry to find ways to avoid wasted calls.
• Batching: Batch records when an endpoint supports arrays.
• Minimize Scope: Use the smallest limit, date window, media duration, or result fields necessary.
• Skip Discovery: Skip schema/model/list/discovery calls if the user has already provided identifiers.
• Poll, don't retrigger: Keep track of async job IDs, JWTs, and operation names to poll them rather than paying to retrigger the same work.

If your gateway serves an /openapi.json file, it is recommended to use the openapi: key in your registry markdown instead of listing endpoints: manually. This allows pay skills build to automatically resolve pricing and protocol metadata by probing the live 402 challenges.

Supported Forms:

1. Fully-qualified URL (Recommended): Use a https:// URL. The registry validator requires this because the registry is consumed remotely.

   openapi:
     url: https://my-api.example.com/openapi.json

2. Inline JSON: Use a YAML literal block for small, static specs.

   openapi:
     content: |
       {
         "openapi": "3.0.0",
         ...
       }

Note: openapi: { path: ... } is not valid in the registry; path: is reserved for local filesystem use with the pay gate api --openapi <file> command.

---
name: my-api
title: "My API"
description: "..."
use_case: "..."
category: data
service_url: https://my-api.example.com
openapi:
  url: https://my-api.example.com/openapi.json
---

When building a Solana Pay application, follow these rules for transaction construction to ensure wallet compatibility:

If the transaction has no signatures:

• The application should set the feePayer to the account provided in the POST request, or the zero value (11111111111111111111111111111111).
• The application should set the recentBlockhash to the latest blockhash, or the zero value.
• Note: The wallet will ignore the feePayer and recentBlockhash in the transaction and overwrite them with the account from the request and the latest blockhash respectively.

If the transaction already has signatures:

• The application must set the feePayer to the public key of the first signature.
• The application must set the recentBlockhash to the latest blockhash.
• The application must serialize and deserialize the transaction before signing to ensure consistent account key ordering.
• The wallet will verify existing signatures and only sign with the account provided in the request.