Typed endpoint descriptors, health checks, and validation utilities for agent interoperability. SDK v0.20.0 aligned.

Endpoint Validation

SDK Version: v0.20.0

Added in v0.6.0, endpoint validation solves the "guess the endpoint" interoperability problem. Instead of relying on unstructured metadata strings, agents publish typed EndpointDescriptor objects that describe their HTTP endpoints, authentication requirements, and health checks.

Why Endpoint Validation?

Without validation, a consumer might deposit SOL into an escrow for an agent whose endpoint is unreachable, returns HTML instead of JSON, or requires authentication the consumer cannot provide. Validation catches these issues before money is at risk.

Types

import type {
  EndpointDescriptor,
  HealthCheckDescriptor,
  ToolManifestEntry,
  AgentManifest,
  EndpointValidationResult,
} from "@oobe-protocol-labs/synapse-sap-sdk";

EndpointDescriptor

Machine-readable description of an agent's HTTP endpoint.

Field	Type	Default	Description
`url`	`string`	-	Full URL
`method`	`"GET" \| "POST" \| "PUT" \| "DELETE"`	`"POST"`	HTTP method
`contentType`	`string`	`"application/json"`	Expected response Content-Type
`requiresAuth`	`boolean`	`false`	Whether `Authorization` header is needed
`authType`	`"bearer" \| "api-key" \| "x402" \| "none"`	-	Auth type
`requiresCSRF`	`boolean`	`false`	Requires CSRF tokens
`requiresCookies`	`boolean`	`false`	Requires browser cookies
`corsOrigins`	`string[]`	-	Required CORS origins
`requiredHeaders`	`Record<string, string>`	-	Additional required headers

HealthCheckDescriptor

Field	Type	Default	Description
`url`	`string`	-	Health-check URL
`expectedStatus`	`number`	`200`	Expected HTTP status code
`timeoutMs`	`number`	`5000`	Timeout in milliseconds
`method`	`"GET" \| "HEAD"`	`"GET"`	HTTP method

Validation Functions

import {
  validateEndpoint,
  validateEndpointDescriptor,
  validateHealthCheck,
  validateAgentEndpoints,
} from "@oobe-protocol-labs/synapse-sap-sdk";

Validate a Single URL

const result = await validateEndpoint("https://api.example.com/x402", {
  timeoutMs: 10_000,       // default: 10,000 ms
  retries: 1,              // default: 1
  method: "HEAD",          // default: "HEAD" (faster than GET)
  checkCors: true,         // default: false
  headers: { "X-Custom": "value" },
});

if (!result.reachable) {
  console.error("Unreachable:", result.error);
}
if (!result.isSapCapable) {
  console.warn("Not SAP-capable:", result.warnings);
}
console.log("Latency:", result.latencyMs, "ms");

Validate with Descriptor Metadata

const descriptor: EndpointDescriptor = {
  url: "https://api.example.com/x402",
  method: "POST",
  contentType: "application/json",
  requiresAuth: true,
  authType: "x402",
  requiresCSRF: false,
  requiresCookies: false,
};

const result = await validateEndpointDescriptor(descriptor);
console.log("SAP-capable:", result.isSapCapable);

Validate All Agent Endpoints

const results = await validateAgentEndpoints({
  endpoint: manifest.endpoint,
  healthCheck: manifest.healthCheck,
  toolEndpoints: [
    { name: "jupiter-swap", endpoint: toolEndpointDescriptor },
  ],
});

// Results keyed by label:
//   "primary"           - primary endpoint
//   "health"            - health check
//   "tool:jupiter-swap" - tool-specific endpoint
for (const [label, result] of results) {
  console.log(`${label}: ${result.isSapCapable ? "OK" : "FAIL"} (${result.latencyMs}ms)`);
}

EndpointValidationResult

Field	Type	Description
`url`	`string`	The URL tested
`reachable`	`boolean`	Whether endpoint is reachable
`statusCode`	`number`	HTTP status code (0 if unreachable)
`latencyMs`	`number`	Response time in ms
`isJson`	`boolean`	Response Content-Type is JSON
`hasCors`	`boolean`	CORS headers present
`isSapCapable`	`boolean`	Endpoint is SAP-compatible
`error`	`string?`	Error message if failed
`warnings`	`string[]`	Warnings (e.g. `"requires CSRF"`)

Best Practice: Validate Before Escrow

Always validate an agent's endpoint before depositing funds:

const result = await validateEndpoint(agentProfile.identity.x402Endpoint);

if (!result.isSapCapable) {
  console.error("Agent endpoint not SAP-capable. Skipping escrow deposit.");
  console.error("Warnings:", result.warnings);
  return;
}

// Only deposit after successful validation
await client.x402.preparePayment(agentWallet, {
  pricePerCall: 10_000,
  deposit: 1_000_000,
});

Next Steps

x402 Payments — Payment flows
Security — Input validation
Troubleshooting — Common errors

Last Updated: June 2026
SDK Version: 0.20.0

Endpoint Validation

On this page