{"openapi":"3.1.0","info":{"title":"Alder & Pine Home: agent shopping API","version":"2026-04-08","description":"Alder & Pine Home sells to AI agents over UCP (Universal Commerce Protocol). Agents search the catalog, build a checkout and, where they may, complete it. Alder & Pine Home is a demonstration store: it is fictitious, and nothing is sold or charged (test mode).\n\n**Who may do what.** Without a key an agent may browse. To buy, an agent needs a key: one the store issues, or one an AI app gets when its person connects it through the store's sign-in (MCP at /mcp, OAuth). An agent acting for a shopper never pays: completing a checkout sends the cart to the shopper, who approves and pays on their own device, within the spending limit and end date they set.\n\n**Who stands behind the agent.** The store also checks, when an agent sends them, its operator's signature (Web Bot Auth: `Signature`, `Signature-Input` and `Signature-Agent` headers, RFC 9421) and a KYA token (`kyapay-token` header, Skyfire). A store can sell only to signed or verified agents. A signature or token that doesn't hold up is refused, and the first one seen on a key is bound to it.\n\nTerms: https://shop.silverlakefinancialgroup.com/terms","termsOfService":"https://shop.silverlakefinancialgroup.com/terms"},"externalDocs":{"description":"UCP specification","url":"https://ucp.dev/2026-04-08/specification/overview"},"servers":[{"url":"https://shop.silverlakefinancialgroup.com"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"The agent's key (pgk_…): issued by the store, or the access token an AI app gets through the store's OAuth sign-in."},"kyaToken":{"type":"apiKey","in":"header","name":"kyapay-token","description":"A Skyfire KYA token (kya+jwt or kya-pay+jwt), for principal-verified agents."},"webBotAuth":{"type":"apiKey","in":"header","name":"Signature","description":"Web Bot Auth (RFC 9421) with Signature-Input (tag=\"web-bot-auth\") and Signature-Agent. Covers @authority at least."}}},"security":[{},{"agentKey":[]},{"agentKey":[],"kyaToken":[]},{"agentKey":[],"webBotAuth":[]}],"paths":{"/.well-known/ucp":{"get":{"summary":"UCP discovery","operationId":"discover","security":[{}],"responses":{"200":{"description":"Services, capabilities and payment handlers","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/catalog/search":{"post":{"summary":"Search the catalog","operationId":"searchCatalog","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."}],"requestBody":{"required":true,"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"What to look for, e.g. \"sofa\""},"max_price":{"type":"number","description":"In dollars"}},"required":["query"]}}}},"responses":{"200":{"description":"Products with variants, prices, stock and delivery estimates","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"401":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"403":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/catalog/lookup":{"post":{"summary":"Look up products by ID","operationId":"lookupCatalog","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."}],"requestBody":{"required":true,"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Products","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"401":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"403":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/checkout-sessions":{"post":{"summary":"Start a checkout","operationId":"createCheckout","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Repeat a request with the same key to get the same result once."}],"security":[{"agentKey":[]},{"agentKey":[],"kyaToken":[]},{"agentKey":[],"webBotAuth":[]}],"requestBody":{"required":true,"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"line_items":{"type":"array","items":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string","description":"Variant ID from search"}},"required":["id"]},"quantity":{"type":"integer","minimum":1}},"required":["item","quantity"]}},"buyer":{"type":"object","properties":{"email":{"type":"string","format":"email"}}},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"street_address":{"type":"string"},"address_locality":{"type":"string","description":"City"},"address_region":{"type":"string","description":"State, e.g. OR"},"address_country":{"type":"string","description":"ISO country, e.g. US"},"postal_code":{"type":"string"}},"required":["street_address","address_locality","address_country","postal_code"]}},"required":["line_items"]}}}},"responses":{"201":{"description":"The checkout, with totals","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"401":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"403":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/checkout-sessions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a checkout","operationId":"getCheckout","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."}],"security":[{"agentKey":[]}],"responses":{"200":{"description":"The checkout","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"404":{"description":"Not this agent's checkout","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}},"put":{"summary":"Change a checkout","operationId":"updateCheckout","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Repeat a request with the same key to get the same result once."}],"security":[{"agentKey":[]}],"requestBody":{"required":true,"description":"","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"The checkout","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"401":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"403":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/checkout-sessions/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Complete a checkout","operationId":"completeCheckout","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Repeat a request with the same key to get the same result once."}],"security":[{"agentKey":[]},{"agentKey":[],"kyaToken":[]},{"agentKey":[],"webBotAuth":[]}],"description":"For an agent acting for a shopper: sends the cart to the shopper to approve and pay, and answers with a link for them. Refused if it would take the agent over its spending limit.","requestBody":{"required":false,"description":"UCP payment, where the agent may pay","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Completed, or waiting for the shopper","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"401":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"403":{"description":"Refused by the store's door. `messages[0].code` says why: e.g. agent_not_verified, spend_cap_exceeded, signature_invalid, kya_expired, identity_mismatch.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/checkout-sessions/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Cancel a checkout","operationId":"cancelCheckout","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Repeat a request with the same key to get the same result once."}],"security":[{"agentKey":[]}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}},"/ucp/orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read an order this agent placed","operationId":"getOrder","parameters":[{"name":"Request-Id","in":"header","required":true,"schema":{"type":"string"},"description":"A unique ID for each request."},{"name":"UCP-Agent","in":"header","required":false,"schema":{"type":"string"},"description":"The agent's UCP profile, e.g. profile=\"https://agent.example/profile\"."}],"security":[{"agentKey":[]}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}},"404":{"description":"Not this agent's order","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A UCP response object; see https://ucp.dev/2026-04-08/specification/overview"}}}}}}}}}