x402 and Solana wallet setup

DocketLayer uses the x402 payment protocol. When your agent calls a DocketLayer endpoint, it must include a valid payment header containing $0.99 in USDC on Solana. No API keys, no accounts, no subscriptions — the payment is the authentication. This guide covers the three steps to get there: creating a Solana wallet, funding it with USDC, and configuring x402 in your agent code.

How the payment flow works

When your agent calls a DocketLayer endpoint without a payment header, DocketLayer returns an HTTP 402 response containing machine-readable payment details — the price ($0.99), the recipient wallet address, and the accepted currency (USDC on Solana). The x402 client library reads this response, constructs a USDC transaction on Solana, signs it with your wallet's private key, and retries the request with cryptographic proof of payment attached in the Authorization header. DocketLayer verifies the payment on-chain and returns the docket data.

From your code's perspective, this is a single function call. You do not write payment logic. You configure a wallet once, and the x402 library handles the 402 challenge, the payment, and the retry on every request automatically.

Part 1 — Create a Solana wallet

Your agent needs a Solana wallet to hold USDC and sign payment transactions. Two approaches, depending on your setup.

Option A — Programmatic wallet (recommended for agents)

For autonomously operating agents, generate a wallet programmatically. The private key is stored as an environment variable and the agent signs transactions without human involvement at each step.

// Generate a new wallet (run once, save the output securely)
import { Keypair } from "@solana/web3.js";

const wallet = Keypair.generate();
console.log("Public key: ", wallet.publicKey.toBase58());
console.log("Secret key: ", Buffer.from(wallet.secretKey).toString("base64"));

Store the secret key as an environment variable and load it in your agent at runtime:

# .env — never commit this file
SOLANA_PRIVATE_KEY=your_base64_encoded_secret_key

// In your agent
import { Keypair } from "@solana/web3.js";
const secretKey = Buffer.from(process.env.SOLANA_PRIVATE_KEY, "base64");
const wallet = Keypair.fromSecretKey(secretKey);

Option B — Phantom wallet (for testing and manual use)

Install the Phantom browser extension at phantom.app. Create a new wallet, save the seed phrase securely offline, and copy your Solana address. Use this address to receive USDC. For production agents, switch to Option A — Phantom requires a human to approve transactions, which defeats the purpose of autonomous operation.

Part 2 — Fund the wallet with USDC

Each DocketLayer query costs $0.99 in USDC on Solana. Your agent's wallet needs enough USDC to cover your expected query volume before it begins running.

Option A — Purchase directly on an exchange. Buy USDC on Coinbase or Kraken and withdraw to your wallet's Solana address. When withdrawing, confirm you select the Solana network — not Ethereum, Base, or any other chain. USDC sent on the wrong network will not arrive in your Solana wallet.

Option B — Swap from SOL. If you hold SOL, swap to USDC using Jupiter at jup.ag. Connect your wallet, select USDC as the output token, review the rate, and confirm the swap. Jupiter routes through Solana DEXes and typically gives competitive rates.

Verify your USDC balance at Solana Explorer (explorer.solana.com) by searching your wallet's public address and checking the USDC token account balance.

Cases monitored	Daily queries	Monthly cost	Suggested starting balance
10	10	~$30	$50
100	100	~$300	$500
1,000	1,000	~$3,000	$5,000

Set up a monitoring alert when your wallet balance falls below a threshold that would interrupt your agent's workflow. A depleted wallet causes all DocketLayer queries to fail with a payment error — no data is returned, and no charge is applied.

Part 3 — Configure x402 in your agent

Install the x402 library:

npm install x402

Initialize a payment client with your wallet and Solana mainnet connection:

import { createPaymentClient } from "x402";
import { Keypair, Connection } from "@solana/web3.js";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const secretKey = Buffer.from(process.env.SOLANA_PRIVATE_KEY, "base64");
const wallet = Keypair.fromSecretKey(secretKey);

const paymentClient = createPaymentClient({
  wallet,
  connection,
  network: "solana-mainnet",
  currency: "USDC"
});

Use the payment client to query DocketLayer. The library handles the 402 challenge, payment, and retry automatically:

async function queryDocketLayer(caseId, courtCode, lastChecked) {
  const response = await paymentClient.fetch(
    "https://api.docketlayer.com/v1/case",
    {
      method: "GET",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        case_id: caseId,
        court_code: courtCode,
        last_checked: lastChecked
      })
    }
  );

  if (!response.ok) throw new Error(`DocketLayer error: ${response.status}`);
  return response.json();
}

// Example
const result = await queryDocketLayer(
  "1:24-cv-01234",
  "nysd",
  "2026-01-01T00:00:00Z"
);
console.log(result.changed ? result.new_filings : "No changes");

For Python agents, install the Python x402 client:

pip install x402 solana

import os
from x402 import PaymentClient

client = PaymentClient(
    private_key=os.environ["SOLANA_PRIVATE_KEY"],
    network="solana-mainnet",
    currency="USDC"
)

result = client.get(
    "https://api.docketlayer.com/v1/case",
    json={
        "case_id": "1:24-cv-01234",
        "court_code": "nysd",
        "last_checked": "2026-01-01T00:00:00Z"
    }
).json()

print(result["new_filings"] if result["changed"] else "No changes")

Security

Never hardcode your private key. Load it from environment variables or a secrets manager. Never commit it to a repository.
Use a dedicated wallet. Do not use a personal wallet holding significant funds. Fund the agent wallet with only what it needs to operate.
Monitor your balance. A depleted wallet fails silently from the agent's perspective — queries return errors, not empty results.
Rotate keys if compromised. Generate a new wallet, transfer remaining USDC, and update your environment immediately.

Test before going live

DocketLayer's /v1/status endpoint is free and requires no payment. Confirm connectivity before making paid queries:

curl https://api.docketlayer.com/v1/status

When testing paid queries, use a known active case in a covered court and verify that the response structure matches the API reference before deploying to production.