API
On this page
One HTTPS API under https://vulsight-guard.vercel.app/api/v1. It is what the proxy, the SDK, and the MCP server all call, and you can call it yourself. Bodies are JSON. Amounts are decimal strings in the asset's smallest unit, so 100000 is 0.10 USDC. Networks are CAIP-2 ids, the chain family, a colon, and the chain's own id: eip155:84532 is Base Sepolia and eip155:8453 is Base. Solana Devnet is solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 and Solana Mainnet is solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp.
Authentication
Every route except GET /api/v1/status takes your API key as a Bearer token. Keys start with vs_test_ and are shown once, when they are made or rotated. vs_test_ marks the beta, not a test network: a key whose policy allows Base or Solana Mainnet starts the same way. A proxy token is a different secret and is refused here.
export VULSIGHT_API_KEY="<your key>"
curl -s -H "authorization: Bearer $VULSIGHT_API_KEY" \
https://Errors
Every failure is the same envelope, with a code you can branch on.
{
"error": {
"code": "missing_api_key",
"message": "Send your API key as a Bearer token in the Authorization header."
}
}missing_api_key(401). No Authorization header. Send the key as a Bearer token.unknown_api_key(401). The header is malformed, the key is mistyped, or the key was rotated. Check for a stray space, then use the key the Keys page showed when it was made or rotated.revoked_api_key(401). The key was revoked. Make a new one on the keys page.invalid_request(422). The body, the query, or one of the two optional headers (x-vulsight-channel,Idempotency-Key) is wrong. The message names the first bad field or header, so fix it and send it again.not_found(404). No decision with that id belongs to your account. Check the id, and that you are using the key for the right account.unknown_route(404). The path is not a route this API serves. The message lists the routes, so check the path against that list.proxy_not_paired(403). The proxy token inx-vulsight-proxy-tokenand the API key do not identify the same active agent. Use the token shown beside the key when it was made or rotated.proxy_not_enforced(409). The agent behind the key is in observe mode, so a client that asks for enforce mode withx-vulsight-require-mode: enforceis refused. Switch it to enforce on the Agents page.settlement_mismatch(409). The decision was not allowed, or the report's payee, amount, asset, or network (or payer, when the decision named one) differ from what it approved. The message names the field. Report the payment as the decision approved it, on the decision that allowed it.settlement_conflict(409). Another of your decisions already carries this transaction in this direction, and one transfer settles one decision per direction in your account. The message names that decision. Report the payment there, or send the hash of the transfer that settled this decision.settlement_limit(409). The decision already holds eight settlements in this direction, the most one decision accepts. One decision approves one payment, so make a decision for the payment this transfer settled and report it there.idempotency_conflict(409). TheIdempotency-Keywas already used for a different payment. Send a new key for a new payment, or the same body to read that decision again.decision_mode_changed(409). An allowance made in observe mode would have been denied or held, and the agent now enforces its policy. Start a new payment attempt with a newIdempotency-Keyif you used one.decision_not_finalized(409). The guard cannot prove the old allowance completed its reservation check. Start a new payment attempt instead of reusing it. This includes older allowances made without anIdempotency-Key.rate_limited(429). Too many calls this minute. Wait the number of seconds in theretry-afterheader, then send it again.internal(500). Something failed on our side. Try again, and tell us if it keeps happening.
Rate limit
Eight meters: five per key, and three across every key the account holds. Four count the last minute from the rows they wrote, one counts the UTC day on the account row. Three, relays, long polls, and settlement reports, count the current minute in a running instance's memory, so an agent spread over several instances gets each of those ceilings in each instance. Going over answers 429 with a retry-after header in seconds and a sentence naming which ceiling was reached. An account holds at most ten live keys, so revoke one on the Keys page before creating an eleventh.
POST /api/v1/decisions
Ask for a verdict on one payment or one contract call. Send kind: x402_payment with payTo, amountAtomic, asset, network, scheme, and resourceUrl, or kind: evm_call with to, value, data, and network. Both take a sessionId, and either contextExcerpt (the text the payment came from, at most 2000 characters) or contextSha256 (a page already filed for this session). A longer page goes through POST /api/v1/context first, and the payment cites the sha256 it returns. Adding observed402PayTo, the payee the seller's own 402 named, lets the guard catch a payment redirected to someone else. Adding payer, the wallet that will sign, makes a settlement reported from another wallet a settlement_mismatch.
An optional x-vulsight-channel header of sdk, mcp, or api says how the call reached the guard. It defaults to api.
An optional Idempotency-Key header, 1 to 200 characters and one per payment attempt, makes a retry safe. A repeat with the same key and the same body answers the decision already made, in its current status, without creating another decision. An enabled wallet blocklist is checked again before an old allowance is reused, so a new restriction can refuse execution without rewriting the historical approval. A repeat that arrives while the first decision is still being finalized waits for it, so both answer the same final verdict. A repeat with the same key and a different body is a 409 idempotency_conflict. Without the header, every call is decided again.
curl -s -X POST https://{
"id": "df3c92cd-61ef-4705-8f70-a4fe15881c93",
"channel": "api",
"createdAt": "2026-09-03T22:54:48.482Z",
"status": "allowed",
"rules": [
{ "id": "network_allowed", "result": "pass" },
{ "id": "asset_allowed", "result": "pass" },
{ "id": "payee_denylisted", "result": "pass" },
{ "id": "payee_matches_402", "result": "pass" },
{ "id": "payee_allowlisted", "result": "pass" },
{ "id": "amount_per_tx", "result": "pass" },
{ "id": "amount_daily_cap", "result": "pass" },
{ "id": "amount_hold_over", "result": "pass" },
{ "id": "velocity_per_hour", "result": "pass" },
{ "id": "contract_call_denied", "result": "pass" },
{ "id": "injection_suspected", "result": "pass" },
{ "id": "first_time_payee", "result": "pass" }
]
}status is one of allowed, denied, review_pending, review_approved, review_denied, or review_expired. Each rule carries a result of pass, info, review, or deny, and a sentence whenever it is not a pass. An agent in observe mode gets status allowed and a shadowStatus holding the answer enforce mode would have given. Three denials are exempt and come back denied in every mode: a network the policy does not allow, an asset the policy does not allow, and a payee other than the one the seller's own 402 named. The codes are on the reason codes page.
GET /api/v1/decisions
The account's newest decisions, across every agent and every way in. limit is a whole number from 1 to 50 and defaults to 10.
curl -s -H "authorization: Bearer $VULSIGHT_API_KEY" \
"https://[
{
"id": "daf814c5-e82b-41d3-8af2-cb71b5ccd6d8",
"channel": "sdk",
"createdAt": "2026-09-03T21:06:54.047Z",
"status": "review_pending",
"rules": [
{ "id": "network_allowed", "result": "pass" },
{
"id": "injection_suspected",
"result": "review",
"sentence": "The page the agent read contains instructions aimed at the agent."
},
{ "id": "first_time_payee", "result": "pass" }
]
}
]The rules array is trimmed above. A real row carries every rule that ran, in order: the resource rule is included only when the policy lists what the agent may buy, and wallet_blocklist only when optional screening is enabled.
before takes the id of a decision you already hold and returns the page made before it, so repeating the call with the last id of each page walks the whole history back to the account's first decision. An empty array means there is nothing older. An id that is not a decision of yours answers 404, and a value that is not a uuid answers 422.
# The next page: the id of the last row you hold.
LAST=$(curl -s -H "authorization: Bearer $VULSIGHT_API_KEY" \
"https://GET /api/v1/decisions/:id
One decision, with the settlements reported against it. wait is a whole number of seconds from 0 to 30 and defaults to 0. With a wait, the call holds while the decision is in review and returns as soon as a person answers, so you can poll without a busy loop.
Before returning an allowance, this route checks the owning agent's current optional wallet blocklist policy. A new restriction can return denied with wallet_blocklist while the original approval remains in history. This does not undo a payment already settled. Request a new decision after addressing a denial; an old denied decision is not an authorization.
This is an execution check as well as a read. It can answer 409 decision_mode_changed or decision_not_finalized, as described above. The original record remains on the Decisions page and in GET /api/v1/decisions; reported settlements remain on its dashboard detail page, and legitimate late settlement reports are still accepted. A refusal to reuse an allowance does not prove an earlier payment failed. Check that history and your wallet before paying again.
# ID is the id the POST above returned, since a decision belongs to the key that made it.
ID=$(curl -s -H "authorization: Bearer $VULSIGHT_API_KEY" \
"https://{
"id": "91373fee-f5a2-4215-8133-81d8a5bf3907",
"channel": "proxy",
"createdAt": "2026-09-03T22:54:57.707Z",
"status": "allowed",
"rules": [ { "id": "network_allowed", "result": "pass" } ],
"settlements": [
{
"id": "60e3569b-afbc-48f9-bee8-1bb03fba8ba3",
"decisionId": "91373fee-f5a2-4215-8133-81d8a5bf3907",
"network": "eip155:84532",
"txHash": "0xa21697a57de128bd78318f651919c8c6b351299a23edb066c77b501c6dc364be",
"payer": "0x6C5FFE605BE39a8f966259216a39eb4119240fa4",
"payee": "0x1111111111111111111111111111111111111111",
"amountAtomic": "1000",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"direction": "sent",
"reportedAt": "2026-09-03T22:54:58.649Z",
"verifiedAt": null
}
]
}The ids on this page are examples; use one your own key made, as the snippet does. An id that is not a uuid, or belongs to another account, answers 404 not_found rather than saying which of the two it was.
POST /api/v1/context
File a page the agent read before the payment it led to, and wait for this call to answer before you ask for the decision. The guard does not order the two calls for you, and a payment that cites a contextSha256 it has not finished filing is judged as unavailable, not as a pass. text is at most 64 KiB of UTF-8, origin is where it came from (a label of at most 200 characters), and sessionId ties it to the payments in the same run. A text that fills the cap is filed as unavailable without a scan, since the guard cannot tell it from the start of a longer page.
curl -s -X POST https://{
"requestId": "00000000-0000-4000-8000-000000000001",
"sha256": "4c48c3cf2d813e2ee1c1ffd4c38068c05b6ff2d5f96302d108c2235907d1a5f7",
"route": "restrict"
}sha256 is the hash of the text, which you can pass later as contextSha256 instead of sending the page again. route is the wire value the content check returned: pass, which the site and the dashboard show as clear, restrict, shown as flagged, or unavailable when the check could not run. New checks also carry decision: block denies payments citing the page or carrying its current session flag, review requires a person, and allowleaves every payment rule in force. The model and pipeline version are recorded. Older review-only flags can still carry a person's clearance; that clearance never waives a new model block.
GET /api/v1/context/history
Read the content history owned by the account behind your API key. Each filing, including a repeated page or a recheck, gets a requestId. The list returns up to 50 records, newest first. When next is present, send its before and beforeId as query parameters to read the next page.
Download GET /api/v1/context/history/:requestId for the complete submitted text, input hashes, and separate primary and background results. The record distinguishes fresh checks, reuse of earlier results, and failures. Raw seller payment-request bytes, when present, use base64 with a checksum. Request authentication headers and cookies are excluded; secrets included in submitted text or seller data are retained. These records are private to your account and remain until it is deleted, including after an agent is removed. Earlier filings made before history was introduced may have only the excerpt and results already on their decisions.
A payment's download opens the filing it used, with that filing's background comparison. If a reused primary result includes primary.source.requestId, that ID points to an earlier filing on your account; follow its download to inspect the original evidence. Results marked shared_cache omit the other account's identifiers. Older results may have no saved source request.
A filing that cannot save its input or primary result answers 503 content_history_unavailable. Retry before continuing to a payment. A background storage failure is recorded separately and never changes the payment decision. A process interrupted while the database is unavailable can leave an unfinished record; it is not a completed comparison.
POST /api/v1/settlements
Record a payment that settled on chain, so the ledger shows the money that moved. direction is sent from the buyer's side and received from the seller's.
curl -s -X POST https://{
"id": "60e3569b-afbc-48f9-bee8-1bb03fba8ba3",
"decisionId": "91373fee-f5a2-4215-8133-81d8a5bf3907",
"network": "eip155:84532",
"txHash": "0xa21697a57de128bd78318f651919c8c6b351299a23edb066c77b501c6dc364be",
"payer": "0x6C5FFE605BE39a8f966259216a39eb4119240fa4",
"payee": "0x1111111111111111111111111111111111111111",
"amountAtomic": "1000",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"direction": "sent",
"reportedAt": "2026-09-03T22:54:58.649Z",
"verifiedAt": null
}A decisionId that does not belong to your account answers 404 not_found, so report the settlement with the key that made the decision. A report on a decision that was not allowed, or whose payee, amount, asset, or network (or payer, when the decision named one) differ from what the decision approved, answers 409 settlement_mismatch and names the field. The same report posted twice lands once. One transaction settles one decision per direction in your account, so a hash another of your decisions already carries answers 409 settlement_conflict. An EVM hash is stored lowercased, so the case you send does not make a second settlement. A decision accepts eight settlements per direction, room for a transfer that failed and was retried, and the ninth answers 409 settlement_limit.
GET /api/v1/policy
The policy this key's payments are judged against, payee lists included. Every field is explained on the policy page.
curl -s -H "authorization: Bearer $VULSIGHT_API_KEY" \
https://{
"allowedNetworks": ["eip155:84532"],
"allowedAssets": [
{
"network": "eip155:84532",
"address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
}
],
"allowedPayees": [
{
"network": "eip155:84532",
"address": "0x1111111111111111111111111111111111111111"
}
],
"deniedPayees": [],
"blocklistEnabled": false,
"allowedResources": [],
"perTxLimitAtomic": "100000",
"dailyCapAtomic": "1000000",
"holdOverAtomic": "0",
"velocityPerHour": 20,
"autoAllowFirstTimeUnderAtomic": "0",
"contractDenylist": {
"selectors": [],
"addresses": []
},
"reviewTimeoutSeconds": 120
}GET /api/v1/status
The only route with no key. version is the short commit the deployment was built from, the deployment id when the build carried no commit, and dev outside a deployment. database is ok or unavailable, contentCheck is ok, unavailable, or unknown when nothing has been checked yet, and contentCheckAt is when it last ran. A database that does not answer makes the whole route 503.
curl -s https://{
"version": "dev",
"database": "ok",
"contentCheck": "ok",
"contentCheckAt": "2026-09-03T21:08:36.718Z"
}POST /api/v1/proxy/preflight
Checks that an API key and a proxy token belong to the same agent and that the agent is in enforce mode, before a person sends a payment through the proxy by hand (a browser client, for one). Send the key as the Bearer token and the proxy token in x-vulsight-proxy-token. The answer is {"paired":true,"mode":"enforce"}, 403 proxy_not_paired when the two do not identify the same active agent, or 409 proxy_not_enforced when that agent is in observe mode.
export VULSIGHT_PROXY_TOKEN="<your proxy token>"
curl -s -X POST https://Solana payments
Use x402_payment with case-sensitive base58 wallet and mint addresses. Solana USDC has six decimals, so 1000 atomic units is 0.001 USDC. A settlement report's txHash is the base58 Solana transaction signature, not an EVM hash. The ledger links to the correct Solana Explorer cluster.
Select the matching network on Policy before paying. Solana Mainnet moves real USDC; Devnet uses test USDC. Raw Solana instructions are not supported by evm_call. Check a Solana payment with the SDK, the MCP tool, or this API before signing, or send it through the proxy, which inspects a standard sponsored exact USDC transfer before forwarding it.
Hold notifications
A payment held for review can reach you before you open the dashboard. Turn the channels on under Settings: a signed webhook, an email to the address you sign in with, and push to a browser (on iPhone, add the site to the home screen first, then turn push on from there). Every channel carries the same facts: the agent, the amount, the payee, the sentences of the rules that did not pass, when the review closes, and a link that opens the decision with Approve and Deny. The webhook carries the resource URL in full, while the email and the push name the seller by host, so the first link in either is the one that opens the decision. A hold on a contract call carries no resourceUrl, and no amount unless the call is a token transfer or grant the guard can read; every other field is always there. When the held request is an ERC-20 approve or increaseAllowance, the body also carries grant (approve or increase): approve sets what the payee may spend to the amount, increase raises it by that much, and nothing has moved yet.
{
"event": "review_pending",
"decisionId": "daf814c5-e82b-41d3-8af2-cb71b5ccd6d8",
"agent": "Research agent",
"amount": "0.05 USDC",
"payee": "0x3333…3333",
"resourceUrl": "https://The post carries x-vulsight-event: review_pending and x-vulsight-signature: sha256=<hex>, the HMAC-SHA256 of the raw body under the secret Settings showed you once. Check it before you trust the body, and compare in constant time.
import { createHmac, timingSafeEqual } from "node:crypto";
const HEADER = "x-vulsight-signature";
export async function POST(request: Request) {
const secret = process.env.VULSIGHT_WEBHOOK_SECRET;
if (!secret) return new Response("webhook secret not configured", { status: 500 });
const body = await request.text();
const digest = createHmac("sha256", secret).update(body).digest("hex");
const expected = Buffer.from(`sha256=${digest}`);
const given = Buffer.from(request.headers.get(HEADER) ?? "", "utf8");
if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
return new Response("bad signature", { status: 401 });
}
const hold = JSON.parse(body); //Send a test event on Settings posts one signed x-vulsight-event: test under the saved secret, once a minute, and shows what the URL answered, so a receiver that verifies signatures can be checked end to end. Its body carries the event name, an id, and a timestamp, so no two test posts share a signature. Redirects are not followed and private or loopback hosts are refused, on save and again before every post, so the URL must be a public https address on the default port. Email goes only to the address you sign in with, once a six-digit code sent there has been typed back (a sign-in provider that verified the address, such as Google, skips the code), for at most twenty held payments a day. When a test send is refused, the settings page names the cause.
The proxy URL
The proxy is not a route on this API, it is a prefix in front of the seller. Your proxy token goes first, then the seller's URL with its own scheme left out.
https://What it does to a denied and a held payment is on the proxy URL page.