@agent-score/commerce 1.5.1 → 1.7.0

package/dist/index.d.mts

@@ -1,151 +1,222 @@
-import { AgentScoreData } from './core.mjs';
-export { AgentIdentity, AgentMemoryHint, AgentScoreCore, AgentScoreCoreOptions, CreateSessionOnMissing, DenialCode, DenialReason, EvaluateOutcome, VerifyWalletSignerMatchOptions, VerifyWalletSignerResult, buildAgentMemoryHint } from './core.mjs';
+export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AgentScoreCoreOptions, AssessResult, CreateSessionOnMissing, DenialCode, DenialReason, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, VerifyWalletSignerMatchOptions, VerifyWalletSignerResult, buildAgentMemoryHint } from './core.mjs';
 export { P as PaymentSigner, S as SignerNetwork, a as extractPaymentSigner, e as extractPaymentSignerAddress, r as readX402PaymentHeader } from './signer-kCAJUZwp.mjs';
 export { F as FIXABLE_DENIAL_REASONS, b as buildContactSupportNextSteps, a as buildSignerMismatchBody, d as denialReasonStatus, c as denialReasonToBody, i as isFixableDenial, v as verificationAgentInstructions } from './_response-DpB-cm2c.mjs';
-export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, policyToGateOptions, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed } from './identity/policy.mjs';
+export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateOptionsFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed } from './identity/policy.mjs';
 
 /**
- * Google A2A (Agent-to-Agent) Signed Agent Cards builder.
+ * Google A2A (Agent-to-Agent) v1.0 Agent Card builder.
  *
- * Compose the JSON payload for an A2A v1.0 Signed Agent Card that includes the
- * agent's AgentScore identity claims. Returned object is the unsigned card body —
- * the merchant (or agent) signs it with their wallet / signing key before publishing.
+ * Compose the JSON payload for an A2A v1.0 Agent Card per the canonical proto at
+ * https://github.com/a2aproject/A2A/blob/main/specification/a2a.proto. Returned object
+ * is the unsigned card body — wrap with an A2A `AgentCardSignature` (RFC 7515 JWS)
+ * to sign vendor-side before publishing at /.well-known/agent-card.json.
  *
- * Why publish: A2A is a Linux Foundation standard with 150+ orgs (Microsoft, AWS,
- * Salesforce in production). Signed Agent Cards let any A2A-compatible reader discover
- * an agent's verified-identity claims without per-platform integration. AgentScore
- * publishing operator identity in this format means our identity travels with the agent
- * across A2A-aware ecosystems.
+ * Why publish: A2A is a Linux Foundation standard. Signed Agent Cards let any
+ * A2A-compatible reader discover an agent's capabilities + protocol bindings without
+ * per-platform integration. Per UCP §A2A binding, agents serving UCP via the A2A
+ * transport MUST declare the canonical UCP extension URI in `capabilities.extensions[]`
+ * so platforms detect UCP support without re-fetching the profile.
  *
  * Spec reference: https://a2a-protocol.org/latest/
  */
-
-interface A2AAgentCardCapabilities {
-    /** Endpoints the agent exposes — `[{ name: "purchase", path: "/purchase", method: "POST" }, ...]`. */
-    endpoints?: {
-        name: string;
-        path?: string;
-        method?: string;
-    }[];
-    /** Free-form skill tags — `["product-purchase", "regulated-commerce", ...]`. */
-    skills?: string[];
+/** Canonical UCP A2A extension URI — verifiers look for this exact URI in
+ *  `capabilities.extensions[]` to detect UCP support on the agent card. Pinned
+ *  to the 2026-04-08 spec snapshot. */
+declare const UCP_A2A_EXTENSION_URI = "https://ucp.dev/2026-04-08/specification/reference";
+/** Per spec §4.4.6. Each entry advertises one protocol binding the agent supports.
+ *  `supported_interfaces[0]` is the preferred binding (ordered list). */
+interface A2AAgentInterface {
+    /** Interface URL (https in production). */
+    url: string;
+    /** Open string — core values are `JSONRPC`, `GRPC`, `HTTP+JSON`. */
+    protocol_binding: string;
+    /** A2A protocol version, e.g. `"1.0"`. Distinct from the agent's own version. */
+    protocol_version: string;
+    tenant?: string;
+}
+/** Per spec §4.4.2. The org/service that provides the agent. */
+interface A2AAgentProvider {
+    url: string;
+    organization: string;
 }
-/** Per A2A v1.0: an entry in the card's top-level `extensions` array. UCP support
- *  is declared this way (UCP §A2A binding requires `https://ucp.dev/2026-04-08/specification/reference`). */
+/** Per spec §4.4.5. A distinct capability or function the agent performs.
+ *  Lives at the TOP LEVEL of AgentCard (not inside `capabilities`). */
+interface A2AAgentSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    examples?: string[];
+    input_modes?: string[];
+    output_modes?: string[];
+}
+/** Per spec §4.4.4. A protocol extension the agent supports.
+ *  Lives in `capabilities.extensions[]`. `description` and `required` are
+ *  spec-mandated fields, not optional. */
 interface A2AAgentCardExtension {
-    /** Canonical extension URI — for UCP, `https://ucp.dev/2026-04-08/specification/reference`. */
     uri: string;
-    /** Extension-specific params. UCP places `{ capabilities: { "<reverse-dns>": [{ version: "..." }, ...] } }` here. */
+    description: string;
+    required: boolean;
     params?: Record<string, unknown>;
 }
-/** Canonical UCP A2A extension URI — verifiers look for this exact URI in `extensions[]`
- *  to detect UCP support on the agent card. Pinned to the 2026-04-08 spec snapshot. */
-declare const UCP_A2A_EXTENSION_URI = "https://ucp.dev/2026-04-08/specification/reference";
-/** Build the canonical UCP entry for an A2A agent card's `extensions[]` array.
+/** Build the canonical UCP entry for an A2A agent card's `capabilities.extensions[]`
+ *  array.
  *
  *  Per UCP §A2A binding: "Businesses supporting UCP must advertise the extension and
  *  any optional capabilities in their A2A Agent Card to allow platforms to activate
  *  the extension." Pass the `capabilities` map keyed by reverse-DNS service/capability
  *  name (e.g. `dev.ucp.shopping.checkout`), each value a list of `{ version }` records.
  *  Pass `{}` (or omit) when you serve UCP at the discovery layer but have no formal
- *  capability bindings yet — vendors that haven't implemented checkout/cart/etc. should
- *  declare the extension URI without claiming capabilities they don't service.
+ *  capability bindings yet.
+ *
+ *  `required: true` declares the platform must understand UCP to interoperate with
+ *  this agent. Default `false`: UCP is offered but not mandatory.
  */
 declare function ucpA2AExtension(capabilities?: Record<string, Array<{
     version: string;
-}>>): A2AAgentCardExtension;
-interface A2AAgentCardIdentity {
-    /** Issuer of the identity claims — always `"https://agentscore.sh"` for the AgentScore-issued card. */
-    issuer: string;
-    /** Operator id under AgentScore. */
-    operator_id: string;
-    /** KYC tier. */
-    kyc_level: string;
-    /** Sanctions screening result. */
-    sanctions_clear: boolean;
-    /** Age bracket. */
-    age_bracket: string;
-    /** Jurisdiction (ISO-3166-1 alpha-2 or empty). */
-    jurisdiction: string;
-    /** ISO-8601 timestamp of last verification refresh. */
-    verified_at: string | null;
-    /** Verify URL where the identity was minted. */
-    verify_url: string;
+}>>, options?: {
+    required?: boolean;
+}): A2AAgentCardExtension;
+/** Per spec §4.4.3. Optional capabilities the agent supports.
+ *
+ *  Per the canonical proto, `capabilities` declares: streaming, push_notifications,
+ *  extensions (the protocol extensions the agent supports), and extended_agent_card.
+ *  REST-style endpoint metadata does NOT belong here — A2A uses `supported_interfaces`
+ *  on the AgentCard for protocol bindings, and `skills` (top-level) for capability
+ *  descriptions. */
+interface A2AAgentCardCapabilities {
+    streaming?: boolean;
+    push_notifications?: boolean;
+    extensions?: A2AAgentCardExtension[];
+    extended_agent_card?: boolean;
 }
+/** Per spec §4.4.7. JWS signature embedded in an Agent Card.
+ *
+ *  Multiple signatures MAY be attached to a single card. Verifiers reconstruct the
+ *  card body without `signatures` to verify each entry. Format follows RFC 7515 JSON
+ *  Web Signature (JWS). */
+interface A2AAgentCardSignature {
+    /** Base64url-encoded JSON of the protected JWS header. REQUIRED. */
+    protected: string;
+    /** Base64url-encoded computed signature. REQUIRED. */
+    signature: string;
+    /** Optional unprotected JWS header values. */
+    header?: Record<string, unknown>;
+}
+/** Per spec §4.4.1. A2A v1.0 Agent Card body.
+ *
+ *  Per spec §4.4.7, JWS signatures may be embedded directly in the card via the
+ *  `signatures` field; verifiers reconstruct the card body without `signatures` and
+ *  verify each entry. Per-vendor identity attestation can also be expressed via a
+ *  vendor extension entry inside `capabilities.extensions[]`. */
 interface A2AAgentCard {
-    /** A2A protocol version. v1.0 was donated to Linux Foundation. */
-    protocol_version: string;
-    /** Card schema version (this builder emits v1). */
-    card_version: number;
-    /** Agent's display name. */
     name: string;
-    /** One-line description shown to A2A consumers. */
-    description?: string;
-    /** Agent's canonical URL (homepage, Discord, repo, etc.). */
-    url?: string;
-    /** Agent capabilities — endpoints + skills. */
-    capabilities?: A2AAgentCardCapabilities;
-    /** A2A v1.0 extensions array. Use `ucpA2AExtension()` to add the UCP entry. */
-    extensions?: A2AAgentCardExtension[];
-    /** AgentScore identity claims. Empty `null` when no identity is available (pre-KYC). */
-    identity: A2AAgentCardIdentity | null;
-    /** Vendor-specific extras merged at the top level. */
-    extras?: Record<string, unknown>;
+    description: string;
+    /** Ordered; first entry is preferred. */
+    supported_interfaces: A2AAgentInterface[];
+    /** Agent's own version, e.g. `"1.0.0"`. Distinct from the A2A protocol version,
+     *  which lives on each `A2AAgentInterface.protocol_version`. */
+    version: string;
+    capabilities: A2AAgentCardCapabilities;
+    default_input_modes: string[];
+    default_output_modes: string[];
+    /** Per spec §4.4.1 (proto field 12, REQUIRED): the agent must declare ≥1 skill.
+     *  The convenience builder `buildA2AAgentCard` enforces non-empty. */
+    skills: A2AAgentSkill[];
+    provider?: A2AAgentProvider;
+    documentation_url?: string;
+    /** Per spec §4.4.1 (proto field 14, optional): URL to an icon for the agent. */
+    icon_url?: string;
+    /** Per spec §4.4.1 (proto field 13, optional) + §4.4.7: JWS signatures embedded
+     *  in the card. Compute over the canonical card body MINUS this field, then attach. */
+    signatures?: A2AAgentCardSignature[];
+    security_schemes?: Record<string, unknown>;
+    security_requirements?: unknown[];
+    /** Vendor-specific extras merged at top level. */
+    [k: string]: unknown;
 }
 interface BuildA2AAgentCardInput {
-    /** Display name for the agent — e.g. a merchant brand or service name. */
+    /** Agent display name. REQUIRED. */
     name: string;
-    /** Optional one-line description. */
-    description?: string;
-    /** Agent's canonical URL. */
-    url?: string;
-    /** Capabilities — endpoints exposed + skill tags. */
-    capabilities?: A2AAgentCardCapabilities;
-    /** A2A v1.0 extensions to declare on the card. Build the UCP entry with
-     *  `ucpA2AExtension()`. Other A2A extensions can be added the same way. */
+    /** Agent purpose/description. REQUIRED per spec. */
+    description: string;
+    /** The primary interface URL — becomes `supported_interfaces[0].url` (with
+     *  `protocol_binding=HTTP+JSON`, `protocol_version=1.0` by default). For
+     *  multi-binding agents, construct `A2AAgentCard` directly. */
+    url: string;
+    /** Top-level skill declarations — what the agent can do. REQUIRED per spec
+     *  (proto field 12 [field_behavior=REQUIRED]); must have ≥1 entry. */
+    skills: A2AAgentSkill[];
+    /** Agent's own version, e.g. `"1.0.0"`. Distinct from the A2A protocol version. */
+    version?: string;
+    /** A2A v1.0 capability extensions. Build the UCP entry with `ucpA2AExtension()`. */
     extensions?: A2AAgentCardExtension[];
-    /** AgentScore assess data — what `getAgentScoreData(c)` returns or what `assess()` returned directly.
-     *  Pass `null` to emit a card with no identity claims (publishable but unverified). */
-    data?: AgentScoreData | null;
-    /** Override the default issuer URL. Default `"https://agentscore.sh"`. */
-    issuer?: string;
-    /** Override the verify URL. */
-    verifyUrl?: string;
+    /** Capability flag: agent supports streaming responses. */
+    streaming?: boolean;
+    /** Capability flag: agent supports push notifications for async task updates. */
+    push_notifications?: boolean;
+    /** Capability flag: agent serves an extended (more detailed) card when authenticated. */
+    extended_agent_card?: boolean;
+    /** Provider org for the agent. */
+    provider?: A2AAgentProvider;
+    /** URL to additional human-readable documentation. */
+    documentation_url?: string;
+    /** URL to an icon for the agent. */
+    icon_url?: string;
+    /** JWS signatures embedded in the card (per spec §4.4.7). */
+    signatures?: A2AAgentCardSignature[];
+    /** Default input media types (defaults to `["application/json"]`). */
+    default_input_modes?: string[];
+    /** Default output media types (defaults to `["application/json"]`). */
+    default_output_modes?: string[];
+    /** Override the protocol binding for the auto-built primary interface (default `"HTTP+JSON"`). */
+    protocol_binding?: string;
+    /** Override the A2A protocol version for the auto-built primary interface (default `"1.0"`). */
+    a2a_protocol_version?: string;
+    /** Per-scheme security details (key = scheme name). */
+    security_schemes?: Record<string, unknown>;
+    /** Required security requirements for invoking the agent. */
+    security_requirements?: unknown[];
     /** Vendor-specific extras merged at the card top level. */
     extras?: Record<string, unknown>;
 }
 /**
- * Compose an A2A Signed Agent Card body with AgentScore identity claims included.
+ * Compose an A2A v1.0 Agent Card body per the canonical proto.
  *
- * Returns the UNSIGNED card. The vendor signs it with their wallet (typically using
- * the same wallet they use for x402 / MPP payments) and publishes the signed envelope
- * to wherever A2A consumers discover cards (a hosted endpoint, on-chain registry,
- * agent-card-server, etc.). Signing is vendor-side because the agent's signing key
- * never leaves their environment.
+ * Returns the UNSIGNED card. To attach identity claims, sign the serialized body
+ * as an RFC 7515 JWS (`AgentCardSignature`). Vendors can also add an identity-flavored
+ * extension to `capabilities.extensions[]`.
+ *
+ * The single `url` argument becomes the primary `supported_interfaces[0].url`
+ * (with `protocol_binding=HTTP+JSON`, `protocol_version=1.0` by default).
  *
  * Example:
  * ```ts
- * import { buildA2AAgentCard } from '@agent-score/commerce/identity/hono';
- *
- * app.get('/.well-known/agent-card', async (c) => {
- *   const data = getAgentScoreData(c);
- *   const card = buildA2AAgentCard({
- *     name: 'Example Merchant Concierge',
- *     description: 'Buy regulated goods via agent payments.',
- *     url: 'https://agents.example.com',
- *     capabilities: {
- *       endpoints: [{ name: 'purchase', path: '/purchase', method: 'POST' }],
- *       skills: ['product-purchase', 'regulated-commerce'],
- *     },
- *     data,
- *   });
- *   const signed = await yourSign(card);
- *   return c.json(signed);
+ * import { buildA2AAgentCard, ucpA2AExtension } from '@agent-score/commerce';
+ *
+ * const card = buildA2AAgentCard({
+ *   name: 'Example Merchant Concierge',
+ *   description: 'Buy regulated goods via agent payments.',
+ *   url: 'https://agents.example.com',
+ *   version: '1.0.0',
+ *   skills: [
+ *     { id: 'purchase', name: 'Purchase', description: 'Buy products via agent payments.', tags: ['commerce', 'payment'] },
+ *   ],
+ *   extensions: [ucpA2AExtension()],
  * });
+ * const signed = await yourJWSSign(card);
  * ```
  */
 declare function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard;
 
+/**
+ * Construct a UCPSigningKey from a public JWK dict (e.g. the `publicJWK` returned by
+ * `generateUCPSigningKey()`). Validates required fields and rejects symmetric keys that
+ * can't publicly verify a JWS in trust-mode UCP. Mirrors python's
+ * `UCPSigningKey.from_jwk(public_jwk)` classmethod via the `UCPSigningKey.fromJWK`
+ * static-method-style namespace export below.
+ */
+declare function ucpSigningKeyFromJWKImpl(jwk: Record<string, unknown>): UCPSigningKey;
 /**
  * UCP (Universal Commerce Protocol) profile builder.
  *
@@ -165,7 +236,6 @@ declare function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard;
  *
  * Spec reference: https://ucp.dev/
  */
-
 /**
  * UCP per-element shape note: each binding interface (`UCPServiceBinding`,
  * `UCPCapabilityBinding`, `UCPPaymentHandlerBinding`) carries the canonical UCP fields
@@ -187,13 +257,11 @@ interface UCPSigningKey {
     /** JWK x / y / n / e / etc. The full key material; passed through verbatim. */
     [k: string]: unknown;
 }
-/**
- * Construct a UCPSigningKey from a public JWK dict (e.g. the `publicJWK` returned by
- * `generateUCPSigningKey()`). Validates required fields and rejects symmetric keys that
- * can't publicly verify a JWS in trust-mode UCP. Symmetric to Python's
- * `UCPSigningKey.from_jwk(public_jwk)` classmethod.
- */
-declare function ucpSigningKeyFromJWK(jwk: Record<string, unknown>): UCPSigningKey;
+/** Static-method-style namespace on the `UCPSigningKey` interface — mirrors python's
+ *  `UCPSigningKey.from_jwk(jwk)` classmethod. Use as `UCPSigningKey.fromJWK(jwk)`. */
+declare const UCPSigningKey: {
+    fromJWK: typeof ucpSigningKeyFromJWKImpl;
+};
 /** Transport binding — keyed under a service name (e.g., `dev.ucp.shopping`). */
 interface UCPServiceBinding {
     /** Spec version, YYYY-MM-DD per UCP convention. REQUIRED. */
@@ -238,7 +306,8 @@ interface UCPCapabilityBinding {
             max?: string;
         }>;
     };
-    /** Vendor-specific extras (e.g., AgentScore claims block on `sh.agentscore.identity`). */
+    /** Vendor-specific extras allowed per UCP convention (e.g., the AgentScore identity
+     *  capability adds a vendor-namespaced policy declaration here). */
     [k: string]: unknown;
 }
 /** Payment handler binding — keyed under a handler reverse-DNS name (e.g., `com.google.pay`). */
@@ -305,15 +374,18 @@ interface BuildUCPProfileInput {
      *  bindings under `'dev.ucp.shopping'`. */
     services?: Record<string, UCPServiceBinding[]>;
     /** Capabilities map, keyed by capability name. The `sh.agentscore.identity` capability
-     *  is auto-added when `data` is provided. */
+     *  is auto-added when `agentscore_gate` is provided. */
     capabilities?: Record<string, UCPCapabilityBinding[]>;
     /** Payment handlers map, keyed by handler reverse-DNS name. */
     payment_handlers?: Record<string, UCPPaymentHandlerBinding[]>;
     /** JWKS — public keys the merchant signs with. REQUIRED by spec. */
     signing_keys: UCPSigningKey[];
-    /** AgentScore assess data — adds an `sh.agentscore.identity` capability + claims
-     *  block when present. */
-    data?: AgentScoreData | null;
+    /** Merchant gate policy declaration. When provided, the SDK auto-injects an
+     *  `sh.agentscore.identity` capability binding into `capabilities`, with the
+     *  policy as the binding's `config`. Static merchant declaration only — no
+     *  per-operator data ever ends up on the public profile. Per-operator identity
+     *  attestation lives on the AP2 risk-signal endpoint, not here. */
+    agentscore_gate?: AgentScoreGatePolicy;
     /** Optional override for the AgentScore capability schema URL. Field is snake_cased
      *  for cross-language parity with the Python sibling. */
     agentscore_schema_url?: string;
@@ -327,6 +399,24 @@ interface BuildUCPProfileInput {
     /** Vendor-specific extras INSIDE the `ucp` envelope (alongside `version`, `services`, etc.). */
     ucp_extras?: Record<string, unknown>;
 }
+/** Merchant gate policy declared on the UCP profile via `sh.agentscore.identity` capability config.
+ *  All fields optional; merchant declares which AgentScore checks the gate enforces. Snake-case
+ *  field names match the AgentScore API's `/v1/assess` policy contract verbatim — no conversion
+ *  layer between this declaration and what the gate actually enforces at runtime. */
+interface AgentScoreGatePolicy {
+    /** Gate denies if the operator/account behind the agent is not Stripe-Identity-verified. */
+    require_kyc?: boolean;
+    /** Gate denies if the operator/account is flagged by OpenSanctions screening. */
+    require_sanctions_clear?: boolean;
+    /** Gate denies if the verified age (from KYC) is below this threshold. Common values: 18, 21. */
+    min_age?: number;
+    /** ISO-3166-1 alpha-2 country codes the gate accepts. Empty/absent allows any. Mutually exclusive
+     *  with `blocked_jurisdictions` (set one or the other, not both). */
+    allowed_jurisdictions?: string[];
+    /** ISO-3166-1 alpha-2 country codes the gate denies. Empty/absent denies none. Mutually exclusive
+     *  with `allowed_jurisdictions`. */
+    blocked_jurisdictions?: string[];
+}
 /**
  * Compose a UCP profile body for `/.well-known/ucp` publication. Returns the spec-
  * compliant shape: `{ ucp: { version, services, capabilities, payment_handlers, ... },
@@ -334,9 +424,12 @@ interface BuildUCPProfileInput {
  * trust-mode verifiers.
  *
  * Auto-injects `sh.agentscore.identity` as a vendor capability extending both
- * `dev.ucp.shopping.checkout` and `dev.ucp.shopping.cart` when `data` carries a
- * resolved operator. Verifiers that recognize the AgentScore namespace can parse
- * the `claims` block; vanilla UCP agents see a normal extension capability.
+ * `dev.ucp.shopping.checkout` and `dev.ucp.shopping.cart` when `agentscore_gate`
+ * is provided. The capability's `config` carries the merchant's static gate
+ * policy declaration (require_kyc / require_sanctions_clear / min_age /
+ * allowed_jurisdictions / blocked_jurisdictions). NO per-operator data is ever
+ * placed on the public profile — per-operator identity attestation flows through
+ * the AP2 risk-signal endpoint, not here.
  *
  * Example:
  * ```ts
@@ -348,24 +441,87 @@ interface BuildUCPProfileInput {
  *     'dev.ucp.shopping': [
  *       { version: '2026-04-08', spec: 'https://ucp.dev/2026-04-08/specification/overview',
  *         transport: 'mcp', endpoint: 'https://merchant.example/api/ucp/mcp',
- *         schema: 'https://ucp.dev/services/shopping/openrpc.json' },
+ *         schema: 'https://ucp.dev/services/shopping/mcp.openrpc.json' },
  *     ],
  *   },
  *   payment_handlers: {
- *     'sh.agentscore.payment.tempo': [{
- *       id: 'tempo',
- *       version: '2026-04-08',
- *       spec: 'https://agentscore.sh/specification/payment-handlers/tempo',
- *       schema: 'https://agentscore.sh/schemas/payment-handlers/tempo.json',
- *       config: { recipient: TEMPO_ADDR },
- *     }],
+ *     ...mppPaymentHandler({ networks: [{ network: 'tempo-mainnet', chain_id: 4217, recipient: TEMPO_ADDR }] }),
  *   },
  *   signing_keys: [signingKey],
+ *   agentscore_gate: { require_kyc: true, min_age: 21, allowed_jurisdictions: ['US'] },
  * });
  * ```
  */
 declare function buildUCPProfile(input: BuildUCPProfileInput): UCPProfile;
 declare const AGENTSCORE_UCP_CAPABILITY = "sh.agentscore.identity";
+type MppNetwork = 'tempo-mainnet' | 'tempo-testnet' | 'mpp-solana-mainnet' | 'mpp-solana-devnet' | (string & {});
+interface MppNetworkEntry {
+    network: MppNetwork;
+    /** EVM-style chain id (e.g. 4217 for Tempo mainnet). Omit for non-EVM networks. */
+    chain_id?: number;
+    /** Static settlement address. Omit for per-order recipients (e.g. Stripe-derived deposits). */
+    recipient?: string;
+    [k: string]: unknown;
+}
+interface MppPaymentHandlerInput {
+    networks: MppNetworkEntry[];
+}
+type X402Network = `base-${number}` | 'solana-mainnet-beta' | 'solana-devnet' | 'stellar-pubnet' | 'stellar-testnet' | (string & {});
+interface X402NetworkEntry {
+    network: X402Network;
+    /** Static settlement address. Omit for per-order recipients. */
+    recipient?: string;
+    [k: string]: unknown;
+}
+interface X402PaymentHandlerInput {
+    networks: X402NetworkEntry[];
+}
+interface StripeSptPaymentHandlerInput {
+    /** Stripe profile id (the merchant-side network identifier the agent's SPT is scoped to). */
+    profile_id: string;
+}
+/**
+ * Build the `sh.agentscore.payment.mpp` payment handler block for a UCP profile.
+ *
+ * @example
+ * ```ts
+ * buildUCPProfile({
+ *   ...,
+ *   payment_handlers: {
+ *     ...mppPaymentHandler({ networks: [{ network: 'tempo-mainnet', chain_id: 4217 }] }),
+ *   },
+ * });
+ * ```
+ */
+declare function mppPaymentHandler(input: MppPaymentHandlerInput): Record<string, UCPPaymentHandlerBinding[]>;
+/**
+ * Build the `sh.agentscore.payment.x402` payment handler block for a UCP profile.
+ *
+ * @example
+ * ```ts
+ * buildUCPProfile({
+ *   ...,
+ *   payment_handlers: {
+ *     ...x402PaymentHandler({ networks: [{ network: 'base-8453', recipient: '0xabc...' }] }),
+ *   },
+ * });
+ * ```
+ */
+declare function x402PaymentHandler(input: X402PaymentHandlerInput): Record<string, UCPPaymentHandlerBinding[]>;
+/**
+ * Build the `sh.agentscore.payment.stripe_spt` payment handler block for a UCP profile.
+ *
+ * @example
+ * ```ts
+ * buildUCPProfile({
+ *   ...,
+ *   payment_handlers: {
+ *     ...stripeSptPaymentHandler({ profile_id: 'profile_5xKvNqM9BaH' }),
+ *   },
+ * });
+ * ```
+ */
+declare function stripeSptPaymentHandler(input: StripeSptPaymentHandlerInput): Record<string, UCPPaymentHandlerBinding[]>;
 
 /**
  * UCP profile signing helpers (JWKS + JWS).
@@ -498,4 +654,4 @@ declare function verifyUCPProfile(profile: SignedUCPProfile, jwks: JWKSResponse)
  */
 declare function buildJWKSResponse(keys: UCPSigningKey[]): JWKSResponse;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardIdentity, AGENTSCORE_UCP_CAPABILITY, AgentScoreData, type BuildA2AAgentCardInput, type BuildUCPProfileInput, type GeneratedUCPKey, type JWKSResponse, type SignUCPProfileOptions, type SignedUCPProfile, type UCPCapabilityBinding, type UCPPaymentHandlerBinding, type UCPProfile, type UCPProfileBody, type UCPServiceBinding, type UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, buildA2AAgentCard, buildJWKSResponse, buildUCPProfile, generateUCPSigningKey, signUCPProfile, ucpA2AExtension, ucpSigningKeyFromJWK, verifyUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, AGENTSCORE_UCP_CAPABILITY, type AgentScoreGatePolicy, type BuildA2AAgentCardInput, type BuildUCPProfileInput, type GeneratedUCPKey, type JWKSResponse, type MppNetworkEntry, type MppPaymentHandlerInput, type SignUCPProfileOptions, type SignedUCPProfile, type StripeSptPaymentHandlerInput, type UCPCapabilityBinding, type UCPPaymentHandlerBinding, type UCPProfile, type UCPProfileBody, type UCPServiceBinding, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, type X402NetworkEntry, type X402PaymentHandlerInput, buildA2AAgentCard, buildJWKSResponse, buildUCPProfile, generateUCPSigningKey, mppPaymentHandler, signUCPProfile, stripeSptPaymentHandler, ucpA2AExtension, verifyUCPProfile, x402PaymentHandler };