Endpoints & environments

Paybond Kit talks to the Gateway — Paybond's public HTTPS API front door. Most hosted integrations do not need to configure a URL; the SDK defaults to the production Gateway origin.

Hosted endpoints

Route paths carry their own version segment. Examples:

• GET https://api.paybond.ai/v1/auth/principal — resolve tenant scope from a service-account API key
• GET https://api.paybond.ai/.well-known/agent-card.json — A2A discovery
• Harbor proxy routes under https://api.paybond.ai/harbor/...

Use https://api.paybond.ai as the Gateway base URL. Do not append /v1 to the base; individual routes include /v1, /harbor, /protocol, or other prefixes as documented in the Gateway API reference.

SDK defaults

TypeScript and Python Kit packages default to https://api.paybond.ai:

import { Paybond } from "@paybond/kit";

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
});

from paybond_kit import Paybond

paybond = await Paybond.open(api_key=os.environ["PAYBOND_API_KEY"])

Hosted SaaS integrations only need PAYBOND_API_KEY (or apiKey / api_key in code). The SDK resolves tenant scope at GET /v1/auth/principal and routes Harbor, Signal, fraud, protocol, and A2A calls through the same Gateway origin.

Overrides for staging or self-hosted deployments

Override the Gateway origin only when you are not calling the hosted SaaS stack:

TypeScript (Paybond.open):

const paybond = await Paybond.open({
  apiKey: process.env.PAYBOND_API_KEY!,
  gatewayBaseUrl: process.env.PAYBOND_GATEWAY_URL,
});

TypeScript scaffold helper (reads env automatically):

import { openPaybondFromEnv } from "@paybond/kit/init";

const paybond = await openPaybondFromEnv();

Python (Paybond.open):

paybond = await Paybond.open(
    api_key=os.environ["PAYBOND_API_KEY"],
    gateway_base_url=os.environ.get("PAYBOND_GATEWAY_URL", "https://api.paybond.ai"),
)

Python scaffold helper (reads env automatically):

from paybond_kit.init import open_paybond_from_env

paybond = await open_paybond_from_env()

PAYBOND_GATEWAY_URL wins over PAYBOND_GATEWAY_BASE_URL in scaffold and MCP helpers when both are set.

Never pass tenant IDs from unauthenticated user input to select a Gateway host. Tenant scope always comes from the authenticated credential, not from a caller-chosen base URL.

Not a model-provider proxy

Paybond is not a drop-in LLM inference proxy for OpenAI, Anthropic (Claude), Google (Gemini), or any other model host. Do not point a provider client's base endpoint — baseURL, API host, or equivalent — at https://api.paybond.ai (or https://api.paybond.ai/v1) and expect chat, completions, responses, or embedding traffic to work.

Integrate Paybond at the tool and spend boundary: create or bootstrap an intent, verify the capability before a paid or side-effecting tool runs, then submit evidence. The model client stays on the provider; Paybond governs delegated spend around your tools across OpenAI, Gemini, Claude/Anthropic, Vercel AI SDK, LangGraph, MCP hosts, and custom orchestrators.

See Agent integrations for runtime examples, including OpenAI Agents SDK.

Direct HTTP callers

When calling Gateway without the Kit:

1. Send Authorization: Bearer <service-account-api-key> or a session JWT as documented in Authentication & tenant binding.
2. Prefix requests with the Gateway origin: https://api.paybond.ai.
3. Attach x-tenant-id only where a route requires it, and only with the tenant realm echoed by GET /v1/auth/principal for your credential.

Harbor and Signal are not browser-facing origins in the hosted stack. Gateway proxies tenant-scoped Harbor and Signal work; SDK callers do not configure separate Harbor URLs.

Related

• Authentication & tenant binding
• Gateway API reference
• Architecture — public origins
• Agent integrations