{"openapi":"3.0.3","info":{"title":"Port66 Agent API","description":"Machine-payable API for the Port66 luxury marketplace. Paid endpoints require a Valiron trust check before x402 returns an HTTP 402 challenge with exact USDC-on-Base payment requirements. Tokenized physical inventory under /api/v1/tokenized-skus is free and unauthenticated — those paths declare `security: []` and need neither trust nor payment.","version":"1.0.0","contact":{"name":"Port66","email":"itsmoizmughal@gmail.com","url":"https://port66.xyz"}},"servers":[{"url":"https://port66.xyz"}],"components":{"securitySchemes":{"valironAgent":{"type":"apiKey","in":"header","name":"x-agent-id","description":"ERC-8004 agent ID evaluated by Valiron. Key-based agents may send x-agent-address instead."},"x402":{"type":"apiKey","in":"header","name":"payment-signature","description":"x402 protocol payment (scheme: exact, network: eip155:8453, USDC). Request without payment to receive the 402 challenge."},"merchantApiKey":{"type":"http","scheme":"bearer","description":"Merchant API key (`p66_live_…`) for tokenizing your own inventory. Scoped to the tokenized-SKU API and to the issuing merchant: it cannot reach orders, payments or account settings, and cannot issue further keys. Issue one from your account at /sku/list."}}},"paths":{"/api/agent/v1":{"get":{"operationId":"getManifest","summary":"Capability manifest (free)","description":"Free machine-readable description of all agent endpoints and pricing.","security":[],"responses":{"200":{"description":"Manifest JSON"}}}},"/api/agent/v1/listings":{"get":{"operationId":"searchListings","summary":"Search and browse active marketplace listings","description":"Paid via x402: $0.005 USDC on Base mainnet per request.","security":[{"valironAgent":[],"x402":[]}],"x-payment-info":{"protocol":"x402","scheme":"exact","network":"eip155:8453","asset":"USDC","price":"$0.005"},"parameters":[{"name":"q","in":"query","required":false,"description":"Free-text search","schema":{"type":"string"}},{"name":"brandName","in":"query","required":false,"description":"Filter by brand name","schema":{"type":"string"}},{"name":"categoryName","in":"query","required":false,"description":"Filter by category name","schema":{"type":"string"}},{"name":"condition","in":"query","required":false,"description":"Item condition","schema":{"type":"string","enum":["DEADSTOCK","MINT","EXCELLENT","VERY_GOOD","GOOD","FAIR"]}},{"name":"minPrice","in":"query","required":false,"description":"Minimum price (USD)","schema":{"type":"number"}},{"name":"maxPrice","in":"query","required":false,"description":"Maximum price (USD)","schema":{"type":"number"}},{"name":"sortBy","in":"query","required":false,"description":"Sort field (e.g. price, listedAt)","schema":{"type":"string"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"description":"Page number (default 1)","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"description":"Results per page (max 50)","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Matching listings with pagination meta","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"totalPages":{"type":"integer"}}},"listings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"},"price":{"type":"number","nullable":true},"currency":{"type":"string"},"listingType":{"type":"string"},"condition":{"type":"string"},"size":{"type":"string","nullable":true},"brand":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"image":{"type":"string","nullable":true},"seller":{"type":"string","nullable":true},"verificationLevel":{"type":"string"},"anchoredOnBase":{"type":"boolean"},"listedAt":{"type":"string"}}}}}}}}},"402":{"description":"x402 payment required — challenge in the payment-required header"}}}},"/api/agent/v1/listings/{slug}":{"get":{"operationId":"getListing","summary":"Full detail for one listing","description":"Paid via x402: $0.005 USDC on Base mainnet per request. Includes description, images, seller, verification level, and on-chain provenance.","security":[{"valironAgent":[],"x402":[]}],"x-payment-info":{"protocol":"x402","scheme":"exact","network":"eip155:8453","asset":"USDC","price":"$0.005"},"parameters":[{"name":"slug","in":"path","required":true,"description":"Listing slug (from search results)","schema":{"type":"string"}}],"responses":{"200":{"description":"Listing detail","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"price":{"type":"number","nullable":true},"minimumOffer":{"type":"number","nullable":true},"currency":{"type":"string"},"listingType":{"type":"string"},"status":{"type":"string"},"condition":{"type":"string"},"size":{"type":"string","nullable":true},"color":{"type":"string","nullable":true},"material":{"type":"string","nullable":true},"era":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"brand":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"category":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"images":{"type":"array","items":{"type":"string"}},"seller":{"type":"object","nullable":true,"properties":{"username":{"type":"string"},"verified":{"type":"boolean"}}},"verificationLevel":{"type":"string"},"provenance":{"type":"object","properties":{"anchoredOnBase":{"type":"boolean"},"txHash":{"type":"string","nullable":true},"registryAddress":{"type":"string","nullable":true},"anchoredAt":{"type":"string","nullable":true}}},"stats":{"type":"object","properties":{"views":{"type":"integer"},"saves":{"type":"integer"},"offers":{"type":"integer"}}},"listedAt":{"type":"string"}}}}}},"402":{"description":"x402 payment required"},"404":{"description":"Listing not found"}}}},"/api/agent/v1/market/{slug}":{"get":{"operationId":"getMarketData","summary":"Market data for a product","description":"Paid via x402: $0.01 USDC on Base mainnet per request. Price history + market statistics.","security":[{"valironAgent":[],"x402":[]}],"x-payment-info":{"protocol":"x402","scheme":"exact","network":"eip155:8453","asset":"USDC","price":"$0.01"},"parameters":[{"name":"slug","in":"path","required":true,"description":"Product slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Market data","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"brand":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}}}},"marketData":{"type":"object","nullable":true,"description":"Aggregate market statistics for the product"},"priceHistory":{"type":"array","description":"Historical price points (up to 1 year)","items":{"type":"object","properties":{"date":{"type":"string"},"price":{"type":"number"}}}}}}}}},"402":{"description":"x402 payment required"},"404":{"description":"Product not found"}}}},"/api/v1/tokenized-skus":{"post":{"operationId":"createTokenizedSku","summary":"Create a tokenized SKU (merchant API key or session)","description":"Registers a SKU you hold physically. No catalogue entry is required: supply `title` and the item describes itself. This does NOT mint anything on-chain — the ERC-1155 claim is minted when someone buys.","security":[{"merchantApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchantSku","unitPriceUsdc","physicalStock"],"description":"Provide exactly one of listingId, productId, or title to identify the item.","properties":{"title":{"type":"string","description":"Item name. Use this when the item is not in the marketplace catalogue — no Product, Brand or Category record is created."},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":12,"description":"https URLs."},"brandName":{"type":"string","description":"Brand or maker as free text. Creates no Brand record and is never reported as verified."},"listingId":{"type":"string","description":"Tokenize from your own marketplace listing."},"productId":{"type":"string","description":"Catalogue product id."},"merchantSku":{"type":"string","description":"Your own SKU code. Unique per merchant."},"unitPriceUsdc":{"type":"string","description":"Unit price in USDC as a decimal string, e.g. \"4.50\"."},"physicalStock":{"type":"integer","minimum":0,"description":"Units you hold."},"backedSupply":{"type":"integer","minimum":1,"description":"Activate in the same call with this backed supply. Must not exceed physicalStock."},"variantAttributes":{"type":"object","additionalProperties":{"type":"string"}},"tokenId":{"type":"string","description":"ERC-1155 token id. Derived deterministically from (merchant, merchantSku) when omitted."},"metadataHash":{"type":"string","description":"keccak256 of the offchain metadata. Derived server-side when omitted."}}}}}},"responses":{"201":{"description":"The created SKU, in DRAFT status"},"401":{"description":"Missing or invalid credential"},"403":{"description":"Key is not scoped to this endpoint, or the merchant is not enabled for tokenization"},"503":{"description":"Tokenization is disabled on this deployment"}}},"get":{"operationId":"browseTokenizedSkus","summary":"Browse tokenized physical inventory (free)","description":"Public, unauthenticated read of tokenized SKUs: supply, unit price, chain, contract reference and merchant. Responses are wrapped in a `data` envelope. Reports operator records and their on-chain references; it does not assert authenticity or ownership.","security":[],"parameters":[{"name":"status","in":"query","required":false,"description":"SKU status (default ACTIVE)","schema":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","RETIRED"],"default":"ACTIVE"}},{"name":"merchantId","in":"query","required":false,"description":"Filter by merchant id","schema":{"type":"string"}},{"name":"brandSlug","in":"query","required":false,"description":"Filter by brand slug","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Free-text match on product name, brand name or merchant SKU","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number (default 1)","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Results per page (max 50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Matching SKUs with pagination meta","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"productId":{"type":"string","nullable":true,"description":"Null for self-described items outside the marketplace catalogue."},"selfDescribed":{"type":"boolean","description":"True when `product` was synthesised from the merchant's own title/images/brandName rather than a catalogue record. Such items never report a verified brand."},"merchantSku":{"type":"string","description":"Merchant's own SKU code"},"variantAttributes":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Free-form variant map, e.g. { \"color\": \"Natural\" }"},"chain":{"type":"string","enum":["BASE_MAINNET","BASE_SEPOLIA"]},"contractAddress":{"type":"string","description":"ERC-1155 inventory contract"},"tokenId":{"type":"string"},"metadataHash":{"type":"string","nullable":true},"metadataUri":{"type":"string","nullable":true},"unitPriceUsdc":{"type":"string","description":"Unit price in USDC as a decimal string, e.g. \"1500\""},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","RETIRED"]},"physicalStock":{"type":"integer","description":"Units the merchant holds"},"tokenizedStock":{"type":"integer","description":"Units backed on-chain"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"product":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"verified":{"type":"boolean"}}},"category":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}}}},"merchant":{"type":"object","nullable":true,"properties":{"username":{"type":"string"},"displayName":{"type":"string","nullable":true},"businessName":{"type":"string","nullable":true},"verified":{"type":"boolean","description":"Account verification — not a claim about the item"},"merchantVerifiedAt":{"type":"string","format":"date-time","nullable":true},"merchantTier":{"type":"string","nullable":true}}}}}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}}}},"400":{"description":"Invalid query — e.g. limit above 50"}}}},"/api/v1/tokenized-skus/{id}":{"get":{"operationId":"getTokenizedSku","summary":"One tokenized SKU with ledger and on-chain state (free)","description":"Public, unauthenticated detail read. Adds available quantity, the recorded inventory ledger, and on-chain state to the browse shape.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Tokenized SKU id (from the browse response)","schema":{"type":"string"}}],"responses":{"200":{"description":"SKU detail","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"merchantId":{"type":"string"},"productId":{"type":"string","nullable":true,"description":"Null for self-described items outside the marketplace catalogue."},"selfDescribed":{"type":"boolean","description":"True when `product` was synthesised from the merchant's own title/images/brandName rather than a catalogue record. Such items never report a verified brand."},"merchantSku":{"type":"string","description":"Merchant's own SKU code"},"variantAttributes":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Free-form variant map, e.g. { \"color\": \"Natural\" }"},"chain":{"type":"string","enum":["BASE_MAINNET","BASE_SEPOLIA"]},"contractAddress":{"type":"string","description":"ERC-1155 inventory contract"},"tokenId":{"type":"string"},"metadataHash":{"type":"string","nullable":true},"metadataUri":{"type":"string","nullable":true},"unitPriceUsdc":{"type":"string","description":"Unit price in USDC as a decimal string, e.g. \"1500\""},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED","RETIRED"]},"physicalStock":{"type":"integer","description":"Units the merchant holds"},"tokenizedStock":{"type":"integer","description":"Units backed on-chain"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"product":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"brand":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"verified":{"type":"boolean"}}},"category":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"slug":{"type":"string"}}}}},"merchant":{"type":"object","nullable":true,"properties":{"username":{"type":"string"},"displayName":{"type":"string","nullable":true},"businessName":{"type":"string","nullable":true},"verified":{"type":"boolean","description":"Account verification — not a claim about the item"},"merchantVerifiedAt":{"type":"string","format":"date-time","nullable":true},"merchantTier":{"type":"string","nullable":true}}}}},{"type":"object","properties":{"availableQuantity":{"type":"integer","description":"Units currently purchasable"},"ledgerEntries":{"type":"array","description":"Recorded inventory movements (RESERVE, MINT, PURCHASE, REDEEM).","items":{"type":"object"}},"onchain":{"type":"object","nullable":true,"description":"On-chain state read back from the contract, when available."}}}]}}}}}},"404":{"description":"SKU not found"}}}},"/api/v1/tokenized-skus/bulk":{"post":{"operationId":"bulkCreateTokenizedSkus","summary":"Create up to 200 tokenized SKUs in one call","description":"For ERP and catalogue imports. Rows are validated and written independently: one bad row does not fail the import, and the response reports every success and failure by its index in the request.","security":[{"merchantApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":200,"items":{"type":"object","required":["merchantSku","unitPriceUsdc","physicalStock"],"description":"Provide exactly one of listingId, productId, or title to identify the item.","properties":{"title":{"type":"string","description":"Item name. Use this when the item is not in the marketplace catalogue — no Product, Brand or Category record is created."},"description":{"type":"string"},"images":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":12,"description":"https URLs."},"brandName":{"type":"string","description":"Brand or maker as free text. Creates no Brand record and is never reported as verified."},"listingId":{"type":"string","description":"Tokenize from your own marketplace listing."},"productId":{"type":"string","description":"Catalogue product id."},"merchantSku":{"type":"string","description":"Your own SKU code. Unique per merchant."},"unitPriceUsdc":{"type":"string","description":"Unit price in USDC as a decimal string, e.g. \"4.50\"."},"physicalStock":{"type":"integer","minimum":0,"description":"Units you hold."},"backedSupply":{"type":"integer","minimum":1,"description":"Activate in the same call with this backed supply. Must not exceed physicalStock."},"variantAttributes":{"type":"object","additionalProperties":{"type":"string"}},"tokenId":{"type":"string","description":"ERC-1155 token id. Derived deterministically from (merchant, merchantSku) when omitted."},"metadataHash":{"type":"string","description":"keccak256 of the offchain metadata. Derived server-side when omitted."}}}}}}}}},"responses":{"201":{"description":"Per-row outcome. Check `failed` even on a 201.","content":{"application/json":{"schema":{"type":"object","properties":{"requested":{"type":"integer"},"created":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"id":{"type":"string"},"merchantSku":{"type":"string"}}}},"failed":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"merchantSku":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Missing or invalid credential"},"403":{"description":"Key not scoped to this endpoint, or merchant not enabled"}}}},"/api/v1/tokenized-skus/{id}/activate":{"post":{"operationId":"activateTokenizedSku","summary":"Approve backed supply and activate a SKU (merchant API key or session)","description":"Publishes the SKU and records the supply you are backing as a RESERVE ledger entry. Backed supply may not exceed the physical stock you hold. Still no claim is minted — that happens at purchase.","security":[{"merchantApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["backedSupply"],"properties":{"backedSupply":{"type":"integer","minimum":1,"description":"Units to make claimable. Must be <= physical stock."}}}}}},"responses":{"200":{"description":"The activated SKU"},"400":{"description":"Backed supply exceeds physical stock"},"401":{"description":"Missing or invalid credential"},"403":{"description":"Not your SKU, or key not scoped to this endpoint"},"503":{"description":"Tokenization is disabled on this deployment"}}}},"/api/v1/tokenized-skus/merchant/api-keys":{"post":{"operationId":"createMerchantApiKey","summary":"Issue a merchant API key (session only)","description":"Returns the plaintext key ONCE — it is stored only as a hash and cannot be retrieved later. Requires a signed-in session: an API key cannot issue further keys.","security":[{"valironAgent":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Label, e.g. \"warehouse sync\""},"expiresAt":{"type":"string","format":"date-time","nullable":true}}}}}},"responses":{"201":{"description":"The issued key. `key` is shown once and never again.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"key":{"type":"string","description":"Plaintext — store it now"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true}}}}}},"403":{"description":"An API key attempted to issue another key"}}},"get":{"operationId":"listMerchantApiKeys","summary":"List your API keys (session only; never returns secrets)","security":[{"valironAgent":[]}],"responses":{"200":{"description":"Keys with prefix, status and last use"},"403":{"description":"An API key attempted to list keys"}}}}}}