TESTING PLAYBOOK

Use this playbook to validate your integration from discovery payments through post payment data retrieval. All examples build on the concepts in the Coinbase X402 welcome guide.

Tools

• cURL for basic smoke tests.

• Postman or Hoppscotch for manual exploration.

• Automated scripts using the official X402 SDKs (@coinbase/x402, coinbase_x402).

• Environment variables populated as described in Environment Configuration.

Smoke test checklist

1. Health endpoint

   curl "$NEURA_BASE_URL/health"

   Expect 200 with status: healthy.

2. Discovery call (402)

   curl -i "$NEURA_BASE_URL/token/0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/1"

   Verify HTTP/1.1 402 Payment Required and presence of X-402- headers.

3. Invoice settlement Use the Coinbase SDK or your wallet to settle the invoice. Document the transaction hash.

4. Replay with proof

   curl -X GET "$NEURA_BASE_URL/token/0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/1" \
     -H "X-402-Invoice: $INVOICE" \
     -H "X-402-Payment-Proof: $PROOF" \
     -H "X-402-Version: 1"

   Expect 200 with success: true.

Automated regression script (TypeScript)

import { X402Client } from "@coinbase/x402";
import fetch from "node-fetch";

const baseUrl = process.env.NEURA_BASE_URL!;
const client = new X402Client({
  apiKeyName: process.env.CDP_API_KEY_ID!,
  privateKey: process.env.CDP_API_KEY_SECRET!,
  facilitatorUrl: process.env.NEURA_FACILITATOR_URL!,
});

async function ensurePaidGet(path: string) {
  const discovery = await fetch(`${baseUrl}${path}`);
  if (discovery.status !== 402) {
    throw new Error(`Expected 402, got ${discovery.status}`);
  }
  const invoice = discovery.headers.get("x-402-invoice");
  const network = discovery.headers.get("x-402-network") ?? "solana";
  if (!invoice) throw new Error("Missing invoice header");

  const settlement = await client.settleInvoice({ invoice, network });
  const headers = client.buildProofHeaders({
    invoice,
    settlement,
    method: "GET",
    url: `${baseUrl}${path}`,
  });

  const paid = await fetch(`${baseUrl}${path}`, { headers });
  if (!paid.ok) {
    const body = await paid.text();
    throw new Error(`Paid request failed: ${paid.status} ${body}`);
  }
  return paid.json();
}

(async () => {
  const token = await ensurePaidGet("/token/0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/1");
  console.log("Token metadata retrieved", token.timestamp);

  const networks = await ensurePaidGet("/networks");
  console.log("Networks discovered", networks.data.total);
})();

Run the script on a schedule to confirm that credentials, wallets, and facilitator connections remain valid.

Postman collection tips

• Set NEURA_BASE_URL, CDP_API_KEY_ID, and CDP_API_KEY_SECRET as collection variables.

• Create a pre-request script that checks for a cached payment proof; if none exists, trigger the discovery request programmatically, settle the invoice via the Coinbase API, and add the proof headers automatically.

• Store the invoice payload and expiration timestamp in the Postman environment to avoid redundant payments during rapid iteration.

Monitoring and alerts

• Track error rates (success: false) and specific status codes (402, 429, 500).

• Alert if payment settlement fails repeatedly; this often indicates depleted wallet balances or expired facilitator credentials.

• Monitor response latency. Sudden increases may correlate with network congestion or rate limiting.

Troubleshooting checklist

Issue	Steps
Invoice paid but request returns 402	Confirm you replayed the exact HTTP method, URL, and body. Regenerate proof headers using the Coinbase SDK.
400 validation error	Compare payload against the Endpoint Catalog requirements.
429 rate limit	Pause for retryAfter seconds, apply exponential backoff, and reduce concurrency.
500 or 503 errors	Retry with backoff. Capture response bodies for support.

Document findings and share them with Neura support for quick triage when needed.