{"version":"1.0.0","name":"Kifly Agent Commerce Network","description":"Native agent-to-agent commerce. Sellers list products through the Kifly portal; AI agents discover and build carts programmatically via MCP or REST, and the buyer completes payment on a Stripe-powered link — no tool call ever settles a purchase on its own. NO CREDENTIAL IS REQUIRED to search the network, build a cart and obtain that payment link: declare who you are in `meta.ucp-agent.profile` (MCP) or the `UCP-Agent` header (REST) and call us — see the `ai.kifly.open-access` capability, and the per-endpoint `auth` field below, for exactly what is open. A Kifly-issued token adds buyer identity and order history, nothing else. Payment rails: Stripe Payment Link (live, human-confirmed), Coinbase Commerce (beta), x402 USDC on Base (beta).","endpoints":[{"path":"/api/agent/search","method":"GET","description":"Semantic vector search over the seller's catalog. Omit `q` to browse recent products; pass `q=<text>` for multilingual ranked results. Supports filters: `limit`, `sort_by`, `min_price_cents`, `max_price_cents`, `in_stock_only`, `category`, `delivers_to_country` (with optional `delivers_to_region`, `delivers_to_city`, `delivers_to_postal_code`). Pass `facets=true` for counts by category, seller, price band and stock over all matches. Returns JSON-LD ItemList.","requires_payment":false,"auth":"open","scopes":["catalog:read"]},{"path":"/api/agent/sellers","method":"GET","description":"List active sellers on the network: handle, name, city, region, delivery coverage, delivery fee and catalog size. Paginated — pass `cursor` from `kifly:nextCursor` while `kifly:hasMore` is true (default 20, max 50). The discovery entry point for a cross-seller agent: call this, then `/api/agent/seller` for one seller's full delivery coverage.","requires_payment":false,"auth":"open","scopes":["catalog:read:network"]},{"path":"/api/agent/seller","method":"GET","description":"Seller public profile: name, city, delivery coverage (states + cities), delivery fee, catalog size and fulfillment. Name the seller by `handle`, `domain` (any URL on the store's site) or `name`. Call it first when the user names a store: a miss is SELLER_NOT_FOUND with `details.did_you_mean`. Call before create_cart to validate delivery eligibility.","requires_payment":false,"auth":"open","scopes":["catalog:read"]},{"path":"/api/agent/policies","method":"GET","description":"The seller's published store policies — shipping, returns, refunds — as the seller wrote them. Read before telling a buyer what happens after purchase; never infer a policy Kifly was not told. Returns 200 with `available: false` when the seller has published none, which is not an error: it means say so, not guess.","requires_payment":false,"auth":"open","scopes":["catalog:read"]},{"path":"/api/agent/cart","method":"POST","description":"Create a cart. Pass `seller_handle` for network (cross-seller) tokens. Returns `cart_id`.","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/cart/{id}","method":"GET","description":"Read current cart state: line items, quantities, price snapshots, subtotal, and shipping address. Each item includes `item_id` for use with the PATCH/DELETE item endpoints.","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/cart/{id}/items","method":"POST","description":"Add a variant to the cart. Pass `variant_id` (from search results) and `quantity`. Max quantity per item and max cart total are enforced — read `GET /api/agent/platform/limits` before adding items.","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/cart/{id}/items/{itemId}","method":"PATCH","description":"Update the quantity of a cart line item. Set `quantity` to 0 to remove the item. Same per-item quantity ceiling as the add endpoint.","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/cart/{id}/items/{itemId}","method":"DELETE","description":"Remove a single line item from the cart.","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/cart/{id}/shipping-address","method":"POST","description":"Persist a shipping address on the cart and validate delivery coverage. Required before checkout. Returns `delivery_eligible`, `delivery_coverage` (states + cities on failure), and `cart_total_with_delivery_cents` on success (null, with `shipping_priced_at: \"merchant_checkout\"`, when the seller's own checkout prices shipping).","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/quick-buy","method":"POST","description":"Create a cart, add items and set the shipping address in one round trip — the composite of the four cart endpoints above, for an agent that already knows what the buyer wants. Returns the same `cart_id` and delivery verdict. Use the granular endpoints when the buyer is still deciding.","requires_payment":false,"auth":"open","scopes":["cart:write"]},{"path":"/api/agent/cart/{id}/checkout","method":"POST","description":"Read the cart total: returns a 402 challenge (and, for x402 sellers, advertises the USDC option via `X-Payment-Required`). Does NOT settle a card — an `Authorization: Payment` credential is not accepted. Card purchases complete via `/api/agent/payment-link`, which returns a Stripe link the buyer opens and confirms. With `X-Payment: <proof>`: x402 USDC settlement (beta).","requires_payment":true,"auth":"agent_token","scopes":["checkout:write"]},{"path":"/api/agent/payment-link","method":"POST","description":"Create a Stripe Payment Link for a cart. Buyer pays in their browser; agent polls order_status. Optionally includes Coinbase Commerce as alternative payment method when enabled for the seller. Returns `payment_url`, `session_id`, `amount_total_cents`, and `buyer_token_status`.","requires_payment":false,"auth":"open","scopes":["checkout:write","checkout:link"]},{"path":"/api/agent/order-status","method":"GET","description":"Poll a checkout session for payment and fulfillment status. Returns `pending | paid | shipped | failed`. When `shipped`, includes `tracking_number`, `carrier`, and `shipped_at`. A tokenless agent may read only sessions it created, under the same `UCP-Agent` profile it checked out with.","requires_payment":false,"auth":"open","scopes":["checkout:write","checkout:link"]},{"path":"/api/agent/buyer","method":"POST","description":"Register a buyer by email and name. Returns a `buyer_token` (`kfb_live_...`) to persist client-side. If the email already has a Kifly account, returns 409 `BUYER_EXISTS` — recover it via `/api/agent/buyer/otp` + `/api/agent/buyer/verify` instead.","requires_payment":false,"auth":"agent_token","scopes":["buyer:write"]},{"path":"/api/agent/buyer/me","method":"GET","description":"Retrieve the buyer profile associated with a `kfb_live_...` token: name, email, and default shipping address. Pass the token in the `x-kifly-buyer-token` header.","requires_payment":false,"auth":"agent_token","scopes":["order:read"]},{"path":"/api/agent/buyer/orders","method":"GET","description":"List a returning buyer's recent orders + fulfillment status (newest first) — answers 'did my order ship?' in a new session without the original session_id. Pass the `kfb_live_...` token in the `x-kifly-buyer-token` header. Optional `since` (ISO-8601) returns only orders changed after that time; optional `limit` (default 20, max 50).","requires_payment":false,"auth":"agent_token","scopes":["order:read"]},{"path":"/api/agent/buyer/otp","method":"POST","description":"Send a 6-digit verification code to a returning buyer's email so they can recover their saved profile on a new connection — no token pasting. Returns `{ sent: true }`; 404 `buyer_not_found` if the email has no account yet (register instead).","requires_payment":false,"auth":"agent_token","scopes":["buyer:write"]},{"path":"/api/agent/buyer/verify","method":"POST","description":"Verify the 6-digit code emailed to a returning buyer. On success returns a fresh `buyer_token` (`kfb_live_...`) bound to their global profile; 401 `invalid_otp` if the code is wrong or expired.","requires_payment":false,"auth":"agent_token","scopes":["buyer:write"]},{"path":"/api/agent/platform/limits","method":"GET","description":"Current platform constraints: `max_item_quantity` (per line item) and `max_cart_total_cents` / `max_cart_total_usd`. Read at session start to avoid rejection mid-purchase flow. No authentication required.","requires_payment":false,"auth":"none"},{"path":"/api/agent/feedback","method":"POST","description":"Tell us our surface failed you. NO CREDENTIAL REQUIRED — declare yourself with the `UCP-Agent` header (REST) or `meta.ucp-agent.profile` (MCP) and call it. Category + severity required; fire-and-forget (202). If a Kifly endpoint or tool dead-ended you, this is the channel, and it is deliberately the one write you never need a key for.","requires_payment":false,"auth":"open","scopes":["catalog:read:network"]},{"path":"/api/agent/errors","method":"GET","description":"Every error code this platform can return, with the HTTP status it always carries, whether it is retryable, and a `fix` saying what to do about it. Generated from the same table the API emits, so it cannot drift. Read it once and you never have to parse an error message.","requires_payment":false,"auth":"none"},{"path":"/api/agent/docs/{slug}","method":"GET","description":"This platform's integration docs as JSON, for an agent that is stuck and has no human to ask. Slugs include `overview`, `rest` (the REST/UCP surface, incl. both wire forms of the agent identity header), `mcp`, `errors` and `limits`. Returns 404 with an `available` array listing every slug, so one wrong guess is enough to find the right one.","requires_payment":false,"auth":"none"}],"payment":{"protocols":["stripe-payment-link","coinbase-commerce","x402"],"primary":"stripe-payment-link"},"mcp":{"tools":["search_products","get_seller","list_sellers","get_policies","create_cart","add_to_cart","get_cart","update_cart_item","set_shipping_address","quick_buy","checkout","order_status","list_orders","register_buyer","request_buyer_code","verify_buyer","get_buyer_profile","save_buyer_address","get_platform_limits","submit_feedback","request_feature","get_help"],"transports":["http"],"resources":["kifly://platform/limits"],"url":"https://kifly.ai/api/mcp"},"errors":{"envelope":["error","code","fix","retryable","docs","request_id"],"branch_on":["code","fix"],"catalog":"https://kifly.ai/api/agent/errors","count":102},"contact":{"url":"https://kifly.ai","email":"hello@kifly.ai"},"ucp":{"version":"2026-08-25","services":{"ai.kifly.shopping":[{"version":"2026-07-04","spec":"https://kifly.ai/docs/mcp","transport":"mcp","endpoint":"https://kifly.ai/api/mcp","schema":"https://kifly.ai/api/mcp/openrpc.json"}],"dev.ucp.shopping":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/overview","transport":"mcp","endpoint":"https://kifly.ai/api/ucp/mcp","schema":"https://ucp.dev/2026-08-25/services/shopping/mcp.openrpc.json"}]},"capabilities":{"dev.ucp.shopping.catalog.search":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/shopping/catalog/search","schema":"https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json"}],"dev.ucp.shopping.catalog.lookup":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/shopping/catalog/lookup","schema":"https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json"}],"dev.ucp.shopping.cart":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/shopping/cart","schema":"https://ucp.dev/2026-08-25/schemas/shopping/cart.json"}],"dev.ucp.shopping.checkout":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/shopping/checkout","schema":"https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"}],"dev.ucp.shopping.order":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/shopping/order","schema":"https://ucp.dev/2026-08-25/schemas/shopping/order.json"}],"dev.ucp.shopping.fulfillment":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/shopping/extensions/fulfillment","schema":"https://ucp.dev/2026-08-25/schemas/shopping/fulfillment.json","extends":["dev.ucp.shopping.checkout","dev.ucp.shopping.cart"],"config":{"multi_destination":[],"method_combinations":[["shipping"],["pickup"]]}}],"dev.ucp.common.identity_linking":[{"version":"2026-08-25","spec":"https://ucp.dev/2026-08-25/specification/common/identity-linking/","schema":"https://ucp.dev/2026-08-25/schemas/common/identity_linking.json","config":{"scopes":{}}}],"ai.kifly.shopping.search":[{"version":"2026-07-04","spec":"https://kifly.ai/docs/mcp","schema":"https://kifly.ai/api/mcp/openrpc.json"}],"ai.kifly.shopping.cart":[{"version":"2026-07-04","spec":"https://kifly.ai/docs/mcp","schema":"https://kifly.ai/api/mcp/openrpc.json"}],"ai.kifly.shopping.checkout":[{"version":"2026-07-04","spec":"https://kifly.ai/docs/mcp","schema":"https://kifly.ai/api/mcp/openrpc.json","config":{"flow":"hosted_checkout_url"}}],"ai.kifly.shopping.order":[{"version":"2026-07-04","spec":"https://kifly.ai/docs/mcp","schema":"https://kifly.ai/api/mcp/openrpc.json"}],"ai.kifly.open-access":[{"version":"2026-07-04","spec":"https://kifly.ai/docs/rest","schema":"https://kifly.ai/api/mcp/openrpc.json","config":{"credential":"none","identity_field":"meta.ucp-agent.profile","identity_header":"UCP-Agent","identity_required":true,"identity_verified":false,"scopes":["catalog:read:network","cart:write","checkout:link"],"mcp_tools":["search_products","list_sellers","get_seller","get_policies","create_cart","get_cart","add_to_cart","update_cart_item","set_shipping_address","quick_buy","get_help","get_platform_limits","submit_feedback","checkout","order_status"],"rate_limit":{"requests_per_minute":30,"per":"profile"},"settlement":"human_confirmed_payment_link","docs_endpoint":"https://kifly.ai/api/agent/docs/{slug}","profile_hosts":{"reserved":"advisory","refused_from":null},"buyer_context":{"header":"Kifly-Buyer","mcp_meta":"ai.kifly.buyer","fields":["ref","session"],"ref_pattern":"^[A-Za-z0-9._:-]{8,64}$","guidance":"Send HMAC(your secret, your user id); never an email, phone or name."},"signatures":{"required":false,"standard":"RFC 9421","key_sources":["ucp-agent.keys","signature-agent"],"algorithms":["ecdsa-p256-sha256","ecdsa-p384-sha384","ed25519"],"signed_rate_limit":{"per_buyer_per_minute":30,"platform_floor_per_minute":1000,"platform_cap_per_minute":20000},"response_header":"Kifly-Agent-Trust"},"advisories":{"header":"Kifly-Advisory","body_field":"kifly:advisories","mcp_result_meta":"ai.kifly/advisories"}}}]},"payment_handlers":{"ai.kifly.stripe_payment_link":[{"version":"2026-07-04","id":"ai.kifly.stripe_payment_link","spec":"https://kifly.ai/docs/payment-rails","config":{"primary":true,"flow":"hosted_checkout_url","status_endpoint":"https://kifly.ai/api/agent/order-status"}}],"ai.kifly.coinbase_commerce":[{"version":"2026-07-04","id":"ai.kifly.coinbase_commerce","spec":"https://kifly.ai/docs/payment-rails","config":{"stage":"beta"}}],"ai.kifly.x402":[{"version":"2026-07-04","id":"ai.kifly.x402","spec":"https://kifly.ai/docs/payment-rails","config":{"stage":"beta","network":"base","asset":"usdc"}}]}},"keys":[{"kid":"kifly-ucp-2026","kty":"EC","crv":"P-256","x":"_smvZnLaUiusmOgxD5P8G8MpxzFBEXms_F63O6tf2Q8","y":"q4bOoTfEkaFDeWVHaYZIsGvEqN9LF2pgqXF5I-oILZc","use":"sig","alg":"ES256"}]}