Build against the oracle

Quickstart: your first machine paywall

About 60 seconds, and free. No signup and no key: one command triggers a real refusal from the live API.

curl -si "https://keeta-oracle-bounty-2mz3sjj2zq-ue.a.run.app/api/getPrice?pair=BTC-USD" | grep -i payment-required

curl -s -D - -o /dev/null "https://keeta-oracle-bounty-2mz3sjj2zq-ue.a.run.app/api/getPrice?pair=BTC-USD" \
  | tr -d '\r' | awk 'tolower($1)=="payment-required:"{print $2}' \
  | python3 -c "import sys,base64,json; print(json.dumps(json.loads(base64.b64decode(sys.stdin.read().strip())), indent=2))"

You will see plain JSON: the scheme (exact), the network (Solana devnet), the asset (USDC), the amount (5000 base units = $0.005 at USDC's six decimals), where to pay, and the fee sponsor. This is the x402 v2 protocol: the entire price negotiation fits in one response header.

API reference

{ "error": { "code": "STRING_CODE", "message": "text" } }

Paying programmatically

Node 20+. A real x402 v2 client against this API on Solana devnet.

mkdir oracle-buyer && cd oracle-buyer && npm init -y
npm install @x402/fetch@2.18.0 @x402/core@2.18.0 @x402/svm@2.18.0 @solana/kit @scure/base

Fund a devnet wallet with USDC, free: generate a keypair (the code below prints the address on first run), then send it devnet USDC from Circle's faucet at faucet.circle.com (choose Solana devnet). No SOL needed.

// buy-price.mjs  (run: node buy-price.mjs)
import { createKeyPairSignerFromPrivateKeyBytes } from '@solana/kit';
import { base58 } from '@scure/base';
import { wrapFetchWithPayment } from '@x402/fetch';
import { x402Client } from '@x402/core/client';
import { ExactSvmScheme } from '@x402/svm/exact/client';
import { readFileSync, writeFileSync, existsSync } from 'node:fs';

// One-time key setup, persisted locally. Fund the printed address with
// devnet USDC from faucet.circle.com, then run again.
let seed;
if (existsSync('devnet-key.txt')) {
  seed = base58.decode(readFileSync('devnet-key.txt', 'utf8').trim());
} else {
  seed = crypto.getRandomValues(new Uint8Array(32));
  writeFileSync('devnet-key.txt', base58.encode(seed));
}
const signer = await createKeyPairSignerFromPrivateKeyBytes(seed, true);
console.log('buyer wallet:', signer.address);

const client = new x402Client();
client.register('solana:*', new ExactSvmScheme(signer));
const fetchWithPay = wrapFetchWithPayment(fetch, client);

const res = await fetchWithPay(
  'https://keeta-oracle-bounty-2mz3sjj2zq-ue.a.run.app/api/getPrice?pair=BTC-USD',
  { headers: { accept: 'application/json' } }
);
console.log('status:', res.status);
console.log('data:', await res.json());
console.log('settlement receipt:', res.headers.get('payment-response'));

How x402 works here

1. 1

   Client requests a paid resource with no payment. Server answers 402 and puts machine-readable terms in the payment-required response header (base64 JSON; v2 of the protocol).

2. 2

   Client picks acceptable terms, constructs a payment (on Solana: a partially signed USDC transfer where the facilitator pays the network fee), and retries with the PAYMENT-SIGNATURE request header.

3. 3

   A facilitator verifies the payment, the server serves the response, and settlement is submitted on-chain only after success. The receipt travels back in the payment-response header.

Properties worth naming: no accounts, no API keys, no subscriptions, no stored payment methods; price discovery is in-band; refusals are free; buyers need only the stablecoin they spend. This instance settles on Solana devnet so anyone can try it with faucet funds. The same stack has settled on Solana mainnet with real USDC; receipts are on the main page.

The FX anchor

The same project includes an FX anchor on Keeta testnet built on the anchor SDK: it holds a float, quotes KTA to USD conversions, and settled real exchanges end to end, with its endpoints discovered through on-chain resolver metadata rather than any registry. The oracle's own service record is published the same way under the same account. This is what "anchor" means in the Keeta ecosystem: a service whose existence, endpoints, and offerings are readable from the chain itself.

FAQ