Mr Hamlin

Posted on May 16

Spraay just introduced new endpoints for Solana Agents.

#ai #x402 #solana #defi

If you've built a Solana DeFi agent recently, you know the shape of the work.

You write a quote function. It calls Jupiter directly because that's where the liquidity is. Then you need wallet holdings, so you sign up for Helius and stick a key in .env. Then you need price feeds, so you wire up Pyth Hermes. Three providers, three rate limits, three sets of error semantics, three keys to rotate. Your agent does six interesting things and you're managing eight pieces of infrastructure.

I've been building Spraay — an x402 gateway — for several months, and as of today it speaks Solana DeFi natively. Six new endpoints, one gateway, payable per call in USDC. If you're somewhere in the middle of writing the agent I just described, this might save you a weekend.

What's new

GET  /api/v1/solana/jupiter/quote         $0.005
POST /api/v1/solana/jupiter/swap-tx       $0.01
GET  /api/v1/solana/helius/assets-by-owner $0.003
GET  /api/v1/solana/helius/asset          $0.002
GET  /api/v1/solana/pyth/price            $0.005
GET  /api/v1/solana/pyth/prices           $0.008

All six are pure proxies to the real upstream — Jupiter v6, Helius DAS, Pyth Hermes. No synthetic data, no mock responses. Spraay does payment, validation, error normalization, and Bazaar discovery. Your agent does everything else.

What you don't deal with

No accounts. No signup, no email confirmation, no dashboard. Your agent's wallet is its identity.
No API keys. Payment is the auth. You pay $0.005, you get the response.
No bridging. Pay in either Solana USDC (SPL) or Base USDC (ERC-20). Spraay accepts both on every endpoint. Useful when your agent already has USDC on Base from doing other things.
No upstream rate-limit babysitting. Spraay holds the paid tier with Helius and Jupiter. You see clean 402s on success, 429 with retryAfter if upstream rate-limits us.
No custody risk on swaps. Jupiter swap-tx returns an unsigned VersionedTransaction. Your wallet signs and submits. The gateway never touches keys.

Working code

The integration that took me three days to do raw, ported to Spraay in about twenty minutes. The example below uses pseudocode for the payment client — drop in whatever x402 client you're already using:

import { VersionedTransaction, Connection } from "@solana/web3.js";

// Your x402 client of choice — handles the 402 → pay → retry flow
const client = makeX402Client({
  baseUrl: "https://gateway.spraay.app",
  // Pay in Solana USDC, Base USDC, or both — your call
  solanaPrivateKey: process.env.SOLANA_PRIVATE_KEY,
});

const connection = new Connection(process.env.SOLANA_RPC_URL!);

// 1. Read the agent's wallet — SPL tokens, NFTs, native SOL balance, paginated
const holdings = await client.get(
  "/api/v1/solana/helius/assets-by-owner" +
  `?owner=${myWallet.publicKey.toBase58()}&limit=100`
);
console.log(`Wallet holds ${holdings.total} assets, ${holdings.nativeBalance.lamports / 1e9} SOL`);

// 2. Pull live prices for the agent's watchlist in one call
const prices = await client.get(
  "/api/v1/solana/pyth/prices?feedIds=SOL,BTC,ETH,JUP,BONK"
);
const solPrice = prices.prices.SOL.price;  // e.g. 142.37
const solConfidence = prices.prices.SOL.confidence;  // ± confidence interval

// 3. Quote a swap
const quote = await client.get(
  "/api/v1/solana/jupiter/quote" +
  "?inputMint=USDC&outputMint=SOL&amount=10000000&slippageBps=50"
);
console.log(`10 USDC → ${Number(quote.outAmount) / 1e9} SOL via ${quote.routeHops}-hop route`);

// 4. Build the unsigned transaction
const swap = await client.post("/api/v1/solana/jupiter/swap-tx", {
  quoteResponse: quote.raw,
  userPublicKey: myWallet.publicKey.toBase58(),
  prioritizationFeeLamports: "auto",
});

// 5. Sign and submit yourself — gateway never sees the key
const tx = VersionedTransaction.deserialize(
  Buffer.from(swap.swapTransaction, "base64")
);
tx.sign([myWallet]);
const sig = await connection.sendTransaction(tx);
console.log(`Swap submitted: https://solscan.io/tx/${sig}`);

Five operations, four endpoints, one payment rail. The agent pays the per-call cost out of its own wallet, gas-of-the-API-economy style.

Endpoint details, quickly

Jupiter

/quote wraps quote-api.jup.ag/v6/quote (or api.jup.ag/swap/v1/quote on the paid tier — Spraay holds the key). Returns route plan, slippage, output amount, price impact. Accepts symbol aliases (USDC, SOL, BONK, WIF, JUP, etc.) or raw base58 mints.

/swap-tx wraps the /swap endpoint. Returns a base64-encoded VersionedTransaction. Pass the raw quoteResponse from /quote and your userPublicKey. Optional: wrapAndUnwrapSol, prioritizationFeeLamports. Gateway never signs.

Helius DAS

/assets-by-owner wraps getAssetsByOwner. Returns SPL tokens, regular NFTs, compressed NFTs, and native SOL balance in one paginated response. Default limit=100, max 1000. showFungible and showNativeBalance both default true.

/asset wraps getAsset. Returns full metadata for a single asset by mint or compressed NFT ID — image, attributes, royalty info, compression details, ownership.

Pyth

/price wraps Hermes /v2/updates/price/latest for one feed. Returns the human-readable price (already scaled by expo), confidence interval, publish time, and EMA price. Symbol aliases for the obvious ones (SOL, BTC, ETH, USDC, USDT, JUP, PYTH, BONK, WIF, JTO) or pass the 64-char hex feed ID.

/prices is the batch version. Up to 50 feeds, comma-separated. Returns a { symbol: priceObject } map keyed by uppercase symbol.

Trying it before you integrate

Every endpoint returns a clean 402 Payment Required with full x402 payment requirements when you call without paying. You can see the schema, pricing, and accepts arrays directly:

curl -i "https://gateway.spraay.app/api/v1/solana/pyth/price?feedId=SOL"

The 402 body includes both EVM and Solana payment options. Your x402 client picks the rail.

If you want to see all six (plus the rest of Spraay's catalog) in Bazaar-discoverable form:

curl -s "https://gateway.spraay.app/.well-known/x402.json" | jq '.resources[] | select(.resource | contains("/solana/"))'

Error handling notes worth knowing

A few things that will save debugging time:

429 rate_limit means we're being rate-limited by an upstream provider. Response includes retryAfter in seconds. Backoff and retry.
502 upstream_error from any endpoint means the upstream returned a non-2xx. The body contains the actual upstream error in detail. Useful for debugging slippage tolerance, missing feeds, etc.
400 invalid_input_mint etc. are pre-flight validation failures. Spraay never charges you if validation fails before the upstream call.
Pyth feed IDs are case-sensitive hex. If you're not using aliases, lowercase everything or use the alias map.

DEV Community