{"openapi":"3.1.0","info":{"title":"VCCFly Agent Commerce API","version":"1.0.0","description":"Discover inventory, create a budget-bound quote, and purchase with x402 v2.","x-guidance":"For the simplest purchase, call POST /api/agent-commerce/purchase with a SKU or omit both sku and query to select the first available product within budget. Include quantity, agent identity, delivery email, USD budget, idempotency requestId, and explicit human authorization. The first call returns HTTP 402; pay the exact Base USDC requirement and retry the identical request with PAYMENT-SIGNATURE. Use catalog, quotes, and orders only when you need the advanced multi-step flow.","contact":{"email":"jerryy959@outlook.com","url":"https://vccfly.com"}},"servers":[{"url":"https://vccfly.com"}],"paths":{"/api/agent-commerce/catalog":{"get":{"operationId":"searchVccflyProducts","summary":"Search live VCCFly inventory","description":"Free product discovery endpoint. No x402 payment is required.","security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"maxPriceUSD","in":"query","schema":{"type":"number","exclusiveMinimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"Current machine-readable products and inventory.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/agent-commerce/quotes":{"post":{"operationId":"createVccflyQuote","summary":"Create a signed, expiring, budget-bound quote","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Signed quote and x402 purchase instructions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}}}}},"/api/agent-commerce/purchase":{"post":{"operationId":"purchaseVccflyProduct","summary":"Select, quote, pay, and fulfill a VCCFly product through one Agent-friendly endpoint","description":"Provide a SKU or catalog query, or omit both to select the first in-stock item within budget. Include a delivery email, idempotency requestId, and human authorization. The first request returns HTTP 402 for the exact live quote; retry the identical request with PAYMENT-SIGNATURE to settle and fulfill.","tags":["Agent Commerce","x402"],"security":[],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.000001","max":"1000.000000"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseIntentRequest"},"example":{"quantity":1,"requestId":"x402scan-probe-00000001","agent":{"id":"x402scan-discovery-agent"},"delivery":{"email":"buyer@example.com"},"budget":{"maxAmount":1,"currency":"USD"},"authorization":{"approved":true,"approvedBy":"buyer@example.com","approvedAt":"2026-09-27T01:13:26.472Z"}}}}},"responses":{"200":{"description":"Sandbox purchase completed or an idempotent result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"201":{"description":"Payment settled and live order fulfilled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"202":{"description":"Payment settled; fulfillment requires review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"402":{"description":"Payment Required","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agent-commerce/orders":{"post":{"operationId":"purchaseVccflyProductWithX402","summary":"Pay a signed quote and place an idempotent order","description":"The first request returns HTTP 402 with PAYMENT-REQUIRED. An x402 v2 client signs the payment and retries the identical request with PAYMENT-SIGNATURE.","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":16,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"200":{"description":"Sandbox purchase completed or an idempotent result returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"201":{"description":"Payment settled and live order fulfilled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"202":{"description":"Payment settled; fulfillment requires review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"402":{"description":"x402 payment challenge or settlement failure.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 v2 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-payment-protocol":"x402-v2"}},"/api/agent-commerce/orders/{requestId}":{"get":{"operationId":"getVccflyAgentOrder","summary":"Read an Agent Commerce order status","security":[],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Agent-Quote-Token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order status without delivered secret material."}}}}},"components":{"securitySchemes":{"AgentApiKey":{"type":"apiKey","in":"header","name":"X-Agent-Api-Key"}},"schemas":{"Catalog":{"type":"object","properties":{"mode":{"enum":["sandbox","live"]},"currency":{"const":"USD"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}},"required":["mode","currency","items"]},"Product":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"const":"USD"}},"required":["amount","currency"]},"inventory":{"type":"object","properties":{"available":{"type":"integer","minimum":0},"fulfillment":{"const":"digital-email"}},"required":["available","fulfillment"]}},"required":["sku","name","description","price","inventory"]},"QuoteRequest":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1},"agent":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"delivery":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"budget":{"type":"object","properties":{"maxAmount":{"type":"number","exclusiveMinimum":0},"currency":{"const":"USD"}},"required":["maxAmount","currency"]}},"required":["sku","quantity","agent","delivery","budget"]},"QuoteResponse":{"type":"object","properties":{"quote":{"type":"object"},"quoteToken":{"type":"string"},"purchase":{"type":"object"}},"required":["quote","quoteToken","purchase"]},"OrderRequest":{"type":"object","properties":{"quoteToken":{"type":"string"},"agent":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]},"delivery":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"authorization":{"type":"object","properties":{"approved":{"type":"boolean"},"approvedBy":{"type":"string"},"approvedAt":{"type":"string","format":"date-time"}},"required":["approved","approvedBy","approvedAt"]}},"required":["quoteToken","agent","delivery"]},"PurchaseIntentRequest":{"type":"object","additionalProperties":false,"properties":{"sku":{"type":"string","description":"Optional product SKU from the catalog. Omit it to select the first in-stock item matching query and budget."},"query":{"type":"string","maxLength":200,"description":"Optional catalog query used when sku is omitted."},"quantity":{"type":"integer","minimum":1,"maximum":5,"default":1},"requestId":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$","description":"Caller-generated idempotency key. Reuse only for an identical retry."},"agent":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"maxLength":120}},"required":["id"]},"delivery":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","format":"email"}},"required":["email"]},"budget":{"type":"object","additionalProperties":false,"properties":{"maxAmount":{"type":"number","exclusiveMinimum":0},"currency":{"const":"USD"}},"required":["maxAmount","currency"]},"authorization":{"type":"object","additionalProperties":false,"properties":{"approved":{"type":"boolean","const":true},"approvedBy":{"type":"string","minLength":1},"approvedAt":{"type":"string","format":"date-time","description":"Current approval timestamp; must be no more than 24 hours old."}},"required":["approved","approvedBy","approvedAt"]}},"required":["quantity","requestId","agent","delivery","budget","authorization"]},"OrderResponse":{"type":"object","properties":{"idempotent":{"type":"boolean"},"order":{"type":"object","properties":{"id":{"type":"string"},"requestId":{"type":"string"},"status":{"type":"string"},"mode":{"enum":["sandbox","live"]},"amount":{"type":"object","properties":{"value":{"type":"number"},"currency":{"const":"USD"}},"required":["value","currency"]},"payment":{"type":"object"},"fulfillment":{"type":"object"}},"required":["requestId","status","mode","amount","payment","fulfillment"]},"sandboxNotice":{"type":"string"}},"required":["idempotent","order"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"reason":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"externalDocs":{"url":"https://vccfly.com/api/agent-commerce"}}