This page describes the public Kit surface that Paybond supports today across direct SDK usage, agent runtime integrations, MCP hosts, and protocol/A2A clients. If a capability is not listed here, treat it as outside the standard SDK contract unless you have an explicit agreement with Paybond.
Language SDKs
| Surface | Version policy | Runtime | Notes |
|---|---|---|---|
Python paybond-kit | Current stable release line | Python >=3.11 | Published wheels include the native signing extension used by the high-level intent helpers. |
TypeScript @paybond/kit | Current stable release line | Node.js >=22 | ESM package for modern Node.js runtimes. |
Provider-agnostic agent runtime and host integrations
| Integration | Install / surface | Notes |
|---|---|---|
| Direct SDK wrappers | paybond-kit or @paybond/kit | Runtime-neutral pattern using paybond.spendGuard(...) / paybond.spend_guard(...) and the high-level intent helpers. |
| Spend guard helpers | PaybondSpendGuard, authorizeSpend / authorize_spend, guardTool / guard_tool | Gateway-enriched verify before paid tools execute. Distinguishes approval holds (PaybondSpendApprovalRequiredError) from hard denials (PaybondSpendDeniedError). guardTool / guard_tool finalize scope reservations after handler success or failure. |
| Runtime-neutral tool-call adapter | paybondRuntimeToolCallAdapter / paybond_runtime_tool_call_adapter | Dependency-free adapter for provider SDKs, local models, queues, and custom orchestrators that expose a tool-call object plus an application-owned executor. |
| TypeScript app-side wrapper | @paybond/kit | Wrapper pattern using paybond.spendGuard(...) around any side-effecting tool handler. |
| LangGraph | pip install "paybond-kit[langgraph]" | ToolNode awrap_tool_call interceptor pattern (paybond_awrap_tool_call_capability). |
| MCP hosts (Python) | pip install "paybond-kit[mcp]" + paybond-mcp-server | Tenant-bound stdio MCP server. Host-agnostic: works with any MCP-compatible client or runtime. |
| MCP hosts (TypeScript) | npm install @paybond/kit + paybond-mcp-server | Tenant-bound stdio MCP server. Host-agnostic: works with any MCP-compatible client or runtime. |
| Sandbox login | npx -p @paybond/kit paybond login or paybond-kit-login | Browser-approved sandbox device flow that writes PAYBOND_API_KEY to .env.local with mode 0600 and adds the default file to .gitignore when needed. |
| Scaffolds | npx -p @paybond/kit paybond-init --preset paid-tool-guard --framework provider-agnostic --out paybond-paid-tool-guard.ts or paybond-kit-init --preset paid-tool-guard --framework provider-agnostic --out paybond_paid_tool_guard.py | Generates a Paybond guardrail integration helper for provider-agnostic, OpenAI, Gemini, Claude/Anthropic, Vercel AI, LangGraph, or MCP-style paid-tool handlers. |
Paybond verifies tenant scope, intent capabilities, and tool operation names. The Kit does not depend on a specific model provider; callers can use the same spend-guard pattern with hosted models, local models, custom orchestrators, or MCP-compatible hosts.
Settlement rails
| Rail | Status | Notes |
|---|---|---|
stripe_connect | Supported | Destination routing stays server-owned; SDK callers never submit payout destinations. |
stripe_ach_debit | Supported as a requestable rail | Uses delayed bank-debit confirmation through the tenant's linked Stripe destination; SDK callers never submit account or destination details. |
x402_usdc_base | Supported | Intent values stay USD-denominated (currency: "usd", amount_cents, max_spend_usd) while Harbor funds and settles the intent as USDC on Base through the x402 /fund handshake. |
Sandbox tenants can request stripe_ach_debit through the same SDK and admin routing surfaces, but Paybond routes those sandbox intents to simulator destinations. Tenant sandbox testing does not require STRIPE_SECRET_KEY or a real Stripe test-mode Connect account; those credentials are only needed for Paybond's optional Stripe ACH provider smoke tests.
Gateway contracts (service accounts)
| Endpoint | Purpose |
|---|---|
GET /v1/auth/principal | Resolve the service-account tenant realm and environment for hosted SDK and MCP sessions. |
POST /verify | Harbor capability check plus Gateway spend policy enrichment (decision_id, approval_request_id, reason_codes, approval_required, etc.). |
POST /v1/spend/decisions/{decision_id}/complete | Finalize active scope reservations as consumed or released after tool execution (called automatically by guardTool / guard_tool). |
The Gateway deployment must accept service-account credentials on GET /v1/auth/principal and proxy recognition-gated Harbor mutations under /harbor/*.
Harbor HTTP API (Kit-facing)
| Route | Used by Kit |
|---|---|
POST /intents | Principal-signed intent creation through PaybondIntents.create / paybond.intents.create and spend-named aliases createSpendIntent / create_spend_intent. |
POST /intents/{intent_id}/fund | x402 funding through PaybondIntents.fund / paybond.intents.fund. |
POST /verify | Capability checks and spend authorization (Biscuit token, operation, requested spend, optional vendor/task/workflow/tool metadata, optional approval token). Gateway may enrich the response with spend-policy fields. |
POST /intents/{intent_id}/evidence | Signed evidence submission (often after sign_payee_evidence_binding). |
GET /ledger/v1/* | Tenant-scoped provenance reads (tip, authority, events, merkle/latest). |
Signal HTTP API (Kit-facing)
| Route / session | Used by Kit |
|---|---|
ServiceAccountSignalSession.open | Resolves tenant_id from GET /v1/auth/principal using the service-account credential. |
GET /reputation/{operator_did} | Tenant-bound signed receipt lookup. |
GET /signal/v1/portfolio/summary | Tenant-bound portfolio summary lookup. |
GET /signal/v1/portfolio/signed-export | Tenant-bound signed portfolio artifact lookup through getSignedPortfolioArtifact / get_signed_portfolio_artifact. |
GET /signal/v1/operators/{operator_did}/explanation | Tenant-bound explanation delta lookup. |
GET /signal/v1/operators/{operator_did}/review-status | Tenant-bound review-state and trust-policy lookup. |
ServiceAccountFraudSession.open | Resolves tenant_id from GET /v1/auth/principal for fraud review and metrics sessions. |
GET /signal/v1/operators/{operator_did}/review-status | Tenant-bound fraud assessment lookup through GatewayFraudClient.getFraudAssessment / get_fraud_assessment. |
GET /signal/v1/review-queue | Tenant-bound fraud review queue listing with optional state, severity, limit, and score-version filters. |
GET /signal/v1/fraud/metrics | Tenant-bound fraud backtesting and monitoring metrics lookup for 24h, 7d, or 30d windows. |
GET /signal/v1/fraud/release-gate | Tenant-bound fraud release-gate config and metrics reliability lookup. |
PUT /signal/v1/fraud/release-gate | Tenant-admin release-gate mode update for review_only or critical_hold. |
POST /signal/v1/operators/{operator_did}/review-events | Records allowed review workflow/outcome events; SDKs reject non-review and money-movement event types before sending and pass optional signal_code, intent_id, and provider_event_id feedback context. |
Protocol and A2A Gateway API (Kit-facing)
| Route / client | Used by Kit |
|---|---|
GatewayA2AClient | Created by Paybond.open(...) as paybond.a2a for protocol-trust discovery. |
GET /.well-known/agent-card.json | A2A agent card discovery. |
GET /protocol/v2/a2a/task-contracts | A2A task-contract catalog discovery. |
GET /protocol/v2/a2a/task-contracts/{contract_id} | A2A task-contract detail lookup. |
GatewayProtocolClient | Created by Paybond.open(...) as paybond.protocol for protocol-v2 receipts and recognition-gated Gateway Harbor mutations. |
POST /protocol/v2/mandates/verify | Signed AgentMandateV1 verification, exposed through MCP verifier tooling. |
POST /protocol/v2/recognition/verify | Agent recognition proof verification, exposed through MCP verifier tooling. |
POST /protocol/v2/mandates | Recognition-gated mandate import through GatewayProtocolClient.importAgentMandateV1 / import_agent_mandate_v1. |
GET /protocol/v2/receipts/{receipt_id} | Protocol settlement receipt lookup. |
POST /protocol/v2/receipts/verify | Protocol receipt verification. |
POST /harbor/intents | Recognition-gated Gateway Harbor intent creation through paybond.protocol. |
POST /harbor/intents/{intent_id}/fund | Recognition-gated Gateway Harbor funding through paybond.protocol. |
POST /harbor/intents/{intent_id}/evidence | Recognition-gated Gateway Harbor evidence submission through paybond.protocol. |
POST /harbor/intents/{intent_id}/settlement/confirm | Recognition-gated settlement confirmation through paybond.protocol and MCP. The helper confirms the action implied by stored evidence; it does not choose release or refund. |
Boundaries
Settlement confirmation is not part of the high-level paybond.intents helper. For protocol-driven flows use paybond.protocol.confirmHarborSettlement / confirm_harbor_settlement or the paybond_confirm_settlement MCP tool; for human-reviewed operations use the Operator Console.
Compatibility expectations
Paybond validates the supported SDK and integration surfaces in automated testing before release. If you depend on a specific runtime or framework combination, validate it in your own CI against the public quickstarts and examples before rollout.
Sandbox access
To try Kit with a tenant-bound sandbox, create a self-serve Free Developer workspace, issue sandbox service-account keys from the console, and start with one-command guardrails.