Route an agent through the proxy URL

Set up

A seller's URL becomes https://vulsight-guard.vercel.app/p/<proxy token>/<seller url>, with the seller's scheme left out. The seller changes nothing and needs no account here.

1. Copy your proxy URL and export it. It is shown once beside your API key, on Home for your first key and on Keys when you make or rotate one.

   TerminalCopy

   export VULSIGHT_PROXY_URL="<your proxy URL>"

   You see: a URL like https://vulsight-guard.vercel.app/p/vsp_test_.../, ending in a slash.

2. Install an x402 client.

   TerminalCopy

   bun add @x402/fetch @x402/evm viem

   You see: the three packages in your package.json.

3. Make a throwaway wallet in the same shell. Paste its address into the Circle faucet and request test USDC on Base Sepolia.

   TerminalCopy

   export EVM_PRIVATE_KEY="$(
     node --input-type=module -e '
       import { generatePrivateKey } from "viem/accounts";
       console.log(generatePrivateKey());
     '
   )"
   node --input-type=module -e '
     import { privateKeyToAccount } from "viem/accounts";
     const key = process.env.EVM_PRIVATE_KEY;
     console.log(privateKeyToAccount(key).address);
   '

   You see: the wallet's address. The key is exported, never printed.

The token in the URL is a secret, and its vsp_test_ prefix does not mean test money. Keep the full URL out of browser history, shared logs and screenshots. If you did not save it, rotate the key on the Keys page for a new one. Rotating replaces the API key too.

Try it

Ask the demo seller for its dataset through the proxy URL.

curl -i "${VULSIGHT_PROXY_URL}vulsight-guard.vercel.app/merchant/dataset"

HTTP/2 402
cache-control: no-store
content-type: application/json
payment-required: eyJ4NDAyVmVyc2lvbiI6...

{}

That is the seller's own 402, relayed. It makes no decision. The guard decides the retry that carries the signed payment.

This x402 client makes that retry and prints the answer.

import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const need = (name: string) => {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before starting the agent.`);
  return value;
};

const key = need("EVM_PRIVATE_KEY") as `0x${string}`;
const account = privateKeyToAccount(key);
const client = new x402Client().register(
  "eip155:*",
  new ExactEvmScheme(account),
);
const pay = wrapFetchWithPayment(fetch, client);

// The proxy URL shown with your API key, then the seller's URL
// with its scheme left out.
const proxy = need("VULSIGHT_PROXY_URL");
const seller = "vulsight-guard.vercel.app/merchant/dataset";
const res = await pay(proxy + seller);
// 200 allowed or 200 review_approved with the dataset,
// 403 denied with the reasons, or 402 review_pending.
const status = res.headers.get("guard-status");
console.log(res.status, status, await res.text());

Run it with bun agent.ts, or node agent.ts on Node 22.18 or newer with "type": "module" in your package.json. It pays 0.05 test USDC.

HTTP/2 200
cache-control: no-store
content-type: application/json
guard-decision-id: 3f6b2a91-5c0e-4d7a-9b18-2e4f7c6d8a05
guard-settlement-status: reported
guard-status: allowed
payment-response: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6...

{
  "name": "product-reviews",
  "rows": 10000,
  "sample": [...]
}

For a denied payment, point it at /merchant/priority (2.50 USDC). Call client.setSpendControls(false) first, since the x402 client refuses a payment over one dollar before the guard sees it.

What each answer means

Read guard-status first. Sent says whether this request's payment left the proxy.

The proxy writes these headers itself. A seller cannot set them.

Every error code the proxy returns, with its cause and next step, is on Errors. When a seller fails after the payment left, the message says what became of the payment.

Denied and review answers

A denied payment answers 403 with the reasons. Nothing is forwarded.

HTTP/2 403
content-type: application/json
guard-decision-id: 9107cf25-aa34-4d7b-a546-c8b5253634a3
guard-status: denied

{
  "error": {
    "code": "payment_denied",
    "message": "The amount 2.50 USDC is over the per-transaction limit of 0.10 USDC. This payment of 2.50 USDC would bring today's total across all networks to 2.50 USDC, over the daily cap of 1.00 USDC. 0x894d…4807 is not on your allowlist. Auto-allow is off in your policy."
  },
  "decisionId": "9107cf25-aa34-4d7b-a546-c8b5253634a3"
}

The proxy holds a Base payment for review up to 35 seconds while you decide. Approve in time and your client gets the paid answer. Otherwise it gets this 402, and the review stays open.

HTTP/2 402
cache-control: no-store
content-type: application/json
guard-decision-id: daf814c5-e82b-41d3-8af2-cb71b5ccd6d8
guard-status: review_pending
payment-required: eyJlcnJvciI6IlRoaXMgcGF5bWVu...
retry-after: 0

{
  "error": {
    "code": "review_pending",
    "message": "This payment waits on a review, so it was not forwarded yet. Approve or deny it on the Review page at https://vulsight-guard.vercel.app/review before 2026-09-26 14:02:00 UTC, when the review expires. Then send it again after the retry-after seconds, signed afresh if the signature has expired, and the same review answers it."
  },
  "decisionId": "daf814c5-e82b-41d3-8af2-cb71b5ccd6d8"
}

1. Approve or deny the payment on Review.

   You see: the card moves under Resolved in the last day.

2. Request the URL again and sign the 402 it returns.

   You see: 200 with guard-status review_approved, or 403 with review_denied.

3. If the review expired first, do step 2 twice.

   You see: 403 with review_expired, then a new decision.

Stock x402 clients such as @x402/fetch hand the 402 back to your code and do not retry, so your code sends step 2. Give your client a read timeout of at least 60 seconds. A client that gives up sooner can be charged without getting the paid body.

A Solana payment is not held. It gets the 402 at once, with retry-after: 2. The Reviews page has the buttons, the timeout and how to hold a payment on purpose.

Copies and retries

The proxy knows a payment by what was signed. That is an EVM authorization's payer and nonce, or the Solana transaction the buyer signed.

A copy of the same signed payment, such as a library's automatic retry, reads the decision the first send got. It adds nothing to the day's cap or the hour's count.

A payment signed afresh, with a new nonce or a new Solana transaction, is a new attempt. It picks up the decision the proxy kept for the same offer, such as an open or approved review. Otherwise the guard decides it as a new payment.

Request headers

The proxy reads these headers on the way to the seller.

What the proxy checks

• The signed payment. The payer, payee and amount come from the signature, and the asset and network from the seller's 402. The terms must be ones that 402 offered. Then your policy decides, as POST /api/v1/decisions does.
• Every answer it relays: the seller's 402, pages the agent fetches through it, and paid answers. A payment waits while an answer from that seller is still being checked. A flagged page holds or blocks payments to that seller.
• A page flagged for the same seller through the SDK hook, the advisory MCP tool or POST /api/v1/context holds payments to it for an hour. The proxy does not wait for those checks, so wait for their answer before you pay.
• The receipt on the way back. The settlement lands on the ledger without a report from the agent.
• A URL that never answers 402 passes through and makes no decision.

Limits

Past the daily text limit, unpaid requests answer 429 until midnight UTC. Past 64 KiB, the agent still gets the whole answer, and the next payment to that seller waits for your review. Payments decided and pages checked count toward the key's rate limit.

• Only traffic through this URL is checked. The same agent calling the seller directly is not.
• The proxy checks, it never signs. Your key stays on your side, and the guard cannot pay for you or claw a payment back.
• The token lands in logs and shell history. Rotate the key on Keys if it leaks, and the old token can no longer pay.
• The proxy takes x402 v2 and the supported payments only.

The rest of the limits are on the security model page.