Paybond API documentation

Paybond exposes three HTTP surfaces: Harbor, Gateway, and Signal. Together, they cover settlement lifecycle management, authentication and administrative workflows, and signed standing artifacts.

Product surfaces: If the branded names are new, start with Product surfaces. Harbor is the agent transaction engine (signed intents, escrow, evidence, release/refund). Signal is standing & reputation (signed receipts and portfolio exports). Gateway is the API front door — it proxies Harbor and Signal routes and hosts Kit session/auth; it is not a separate marketing product.

All authenticated API calls are scoped to exactly one organization. Requests cannot read or write across organizations, and the authenticated token remains the source of truth for scope. For the platform model behind that behavior, see Tenant model.

Use this page for the rules shared across all three services. Use the service-specific references for request and response details.

Hosted origins

Prefix HTTP requests with the Gateway origin (for example GET https://api.paybond.ai/v1/auth/principal). Route paths carry their own version segment (/v1/…, /harbor/…, /protocol/…); do not treat /v1 as the Gateway base URL.

Harbor does not expose a separate public origin. Use the Gateway Harbor proxy at https://api.paybond.ai/harbor/….

Kit SDKs default to https://api.paybond.ai. Override with gatewayBaseUrl / gateway_base_url on Paybond.open(...), or set PAYBOND_GATEWAY_URL / PAYBOND_GATEWAY_BASE_URL for scaffold helpers and the MCP server. See Endpoints & environments.

Paybond is not a model-provider LLM inference proxy. Model inference stays on OpenAI, Anthropic, Gemini, or your chosen host; Paybond governs delegated spend at the tool boundary via Kit.

Gateway also includes the v2 protocol verification and discovery surface for delegated agent workflows:

• POST /protocol/v2/mandates
• POST /protocol/v2/mandates/verify
• POST /protocol/v2/recognition/verify
• GET /protocol/v2/receipts/{receipt_id}
• POST /protocol/v2/receipts/verify
• GET /.well-known/agent-card.json
• GET /.well-known/agent-receipt-v1.json
• GET /protocol/v2/agent-receipts/{receipt_id}
• GET /protocol/v2/agent-receipts
• POST /protocol/v2/agent-receipts/verify
• GET /protocol/v2/a2a/task-contracts

Signal exposes organization-scoped signed artifacts rather than a shared public reputation plane:

• GET /reputation/{operator_did} returns a signed operator receipt
• GET /signal/v1/portfolio/signed-export returns a signed tenant portfolio artifact

Authentication

Every protected request to Harbor or Gateway must carry one of the following:

1. A session Bearer JWT minted by the Gateway sign-in endpoints (POST /v1/public/auth/login/start and POST /v1/public/auth/challenges/verify, or POST /v1/auth/sso/*). Signed with EdDSA; verify via GET /.well-known/jwks.json. Used by the admin console and browser-originated workflows.
2. A service-account API key sent to Gateway-hosted SDK surfaces such as GET /v1/auth/principal, POST /verify, and POST /harbor/*. Gateway derives any upstream Harbor credentials internally.
3. A dedicated download JWT (aud = paybond-audit-export-download) for signed bundle downloads. Issued alongside the create/get responses for audit exports and must not be mixed with session tokens.

In every case the token carries a tid claim (tenant realm) that is the authorization identity. Unauthenticated identifiers in the request body (tenant_id, org_id) are treated only as hints and must match the token. Kit SDKs do this automatically. When calling the HTTP surfaces directly, you are responsible for attaching Authorization: Bearer … and, where required, the matching x-tenant-id header.

Versioning

• HTTP paths carry their version in the path (/v1/…, /policy/v1/…, /signal/v1/…). Breaking changes bump that segment and ship alongside the previous version until the deprecation window closes.
• Signed artifacts (Signal receipts, portfolio snapshots, audit export manifests) carry an independent schema_version integer plus an artifact_version or receipt_version string. Parsers must reject unknown schema_version values before attempting signature verification.
• Harbor intent signing is versioned inside the signed payload itself (signing_version on create, EvidenceSignV1.version on evidence). Supported create envelopes for fundable intents are signing v6 (raw predicate_dsl) and signing v7 (policy_binding), both requiring payee_pubkey bound in the principal signature. Signing v4/v5 are deprecated and rejected for fundable intents and in live environments. Offline signers should pin to a specific signing payload version supported by their SDK or integration.
• Harbor, Kit, and ledger signing bytes use bincode 2 (bincode::config::standard() / encode_wire). This replaced bincode 1 in 2026-06; signatures from older Kit releases are not valid after Harbor deploy. Evidence binding uses EvidenceSignV1.version = 2; ledger row bodies use format_version = 2.

Signed artifact version matrix

Agent receipt schema discovery: GET /.well-known/agent-receipt-v1.json. Normative spec: Agent receipts. Product guide: Agent Receipt Standard (ARS).

The public API references served under /docs/api/harbor, /docs/api/gateway, and /docs/api/signal pin the current major version for each service. Supporting schema fragments may version independently, but the public docs stay centered on the service pages rather than raw schema files.

Idempotency

Mutating Harbor POST routes honor an optional idempotency-key header (1–256 chars). The key is scoped per authenticated tenant and HTTP operation. Reusing a key with a different request body returns 409 Conflict. Reusing it with the same body replays the original response.

Currently honored by:

• POST /intents
• POST /intents/{intent_id}/fund
• POST /intents/{intent_id}/evidence
• POST /intents/{intent_id}/settlement/confirm

For Harbor-specific route coverage, see the Harbor API reference. Policy-registry POSTs do not honor idempotency keys today, so use natural-key reads (GET …/versions) to detect existing drafts before retrying.

Gateway and Signal endpoints are read-only or status/export oriented and do not require client-supplied idempotency keys today.

Related

• Endpoints & environments — Gateway and Console URLs, env overrides, not a model-provider proxy.
• Harbor predicate DSL — evidence evaluation contract.
• Kit documentation — TypeScript and Python SDK wrappers.
• Platform overview — intent lifecycle, tenant model, and operational surfaces.