{ "openapi": "3.0.4", "info": { "title": "Circles Market API", "description": "Swagger UI for Circles.Market.Api", "version": "v1" }, "paths": { "/api/canonicalize": { "post": { "tags": [ "CanonicalizeEndpoints" ], "summary": "Return the RFC8785-like canonical JSON representation used for signing", "description": "Accepts a JSON-LD CustomDataLink and returns its canonical JSON (without the signature field) using the SDK's CanonicalJson.", "requestBody": { "content": { "application/ld+json; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "413": { "description": "Content Too Large" } } } }, "/api/cart/v1/baskets": { "post": { "tags": [ "CartEndpoints" ], "summary": "Create a new basket", "description": "Body: { operator, buyer, chainId }", "requestBody": { "content": { "application/ld+json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/BasketCreateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/BasketCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" } } } }, "/api/cart/v1/baskets/{basketId}": { "get": { "tags": [ "CartEndpoints" ], "summary": "Get basket by id", "parameters": [ { "name": "basketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found" }, "410": { "description": "Gone" } } }, "patch": { "tags": [ "CartEndpoints" ], "summary": "Patch basket (merge)", "parameters": [ { "name": "basketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "410": { "description": "Gone" } } } }, "/api/cart/v1/baskets/{basketId}/validate": { "post": { "tags": [ "CartEndpoints" ], "summary": "Validate basket", "parameters": [ { "name": "basketId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "422": { "description": "Unprocessable Content" }, "404": { "description": "Not Found" }, "410": { "description": "Gone" } } } }, "/api/cart/v1/baskets/{basketId}/checkout": { "post": { "tags": [ "CartEndpoints" ], "summary": "Checkout basket -> create order id", "parameters": [ { "name": "basketId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "buyer", "in": "query", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "409": { "description": "Conflict" }, "410": { "description": "Gone" } } } }, "/api/cart/v1/baskets/{basketId}/preview": { "post": { "tags": [ "CartEndpoints" ], "summary": "Preview Order snapshot without persisting", "parameters": [ { "name": "basketId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "buyer", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found" }, "410": { "description": "Gone" } } } }, "/api/cart/v1/orders/batch": { "post": { "tags": [ "CartEndpoints" ], "summary": "Get multiple orders by ids for the authenticated buyer", "requestBody": { "content": { "application/ld+json; charset=utf-8": { "schema": { "$ref": "#/components/schemas/BulkOrderRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/BulkOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } } } }, "/api/cart/v1/orders/by-buyer": { "get": { "tags": [ "CartEndpoints" ], "summary": "Get orders for the authenticated buyer address", "responses": { "200": { "description": "OK" } } } }, "/api/cart/v1/orders/{orderId}": { "get": { "tags": [ "CartEndpoints" ], "summary": "Get a single order by id for the authenticated buyer", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } } } }, "/api/cart/v1/orders/by-seller": { "get": { "tags": [ "CartEndpoints" ], "summary": "Get orders (sales) for the authenticated seller address", "responses": { "200": { "description": "OK" } } } }, "/api/cart/v1/orders/{orderId}/as-seller": { "get": { "tags": [ "CartEndpoints" ], "summary": "Get a single order by id for the authenticated seller (filtered view)", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } } } }, "/api/cart/v1/orders/{orderId}/status-history": { "get": { "tags": [ "CartEndpoints" ], "summary": "Get status history for the authenticated buyer", "parameters": [ { "name": "orderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "404": { "description": "Not Found" } } } }, "/api/cart/v1/orders/events": { "get": { "tags": [ "CartEndpoints" ], "summary": "Server-sent events for order status updates of the authenticated buyer", "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" } } } }, "/api/cart/v1/orders/sales/events": { "get": { "tags": [ "CartEndpoints" ], "summary": "Server-sent events for order status updates of the authenticated seller (sales)", "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" } } } }, "/health": { "get": { "tags": [ "Circles.Market.Api" ], "responses": { "200": { "description": "OK" } } } }, "/api/operator/{op}/catalog": { "get": { "tags": [ "Circles.Market.Api" ], "summary": "Aggregates verified product/* links across many avatars under the operator namespace and returns a paged AggregatedCatalog.", "description": "Inputs: operator address path param; repeated ?avatars=...; optional chainId/start/end; cursor/offset pagination. Implements CPA rules (verification, chain domain, nonce replay, time window) and reduces to newest-first product catalog with tombstone support.", "operationId": "OperatorAggregatedCatalog", "parameters": [ { "name": "op", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainId", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "start", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "end", "in": "query", "schema": { "type": "integer", "format": "int64" } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/sellers": { "get": { "tags": [ "Circles.Market.Api" ], "summary": "List all active seller addresses with at least one enabled route.", "description": "Returns distinct seller addresses from enabled market routes. Sellers are returned as lowercase eip155 addresses with their chainId.", "operationId": "ActiveSellers", "responses": { "200": { "description": "OK" } } } }, "/api/auth/challenge": { "post": { "tags": [ "Circles.Market.Api" ], "summary": "Proxy auth challenge to auth-service", "responses": { "200": { "description": "OK" } } } }, "/api/auth/verify": { "post": { "tags": [ "Circles.Market.Api" ], "summary": "Proxy auth verify to auth-service", "responses": { "200": { "description": "OK" } } } }, "/inventory/availability/{chainId}/{seller}/{sku}": { "get": { "tags": [ "InventoryEndpoints" ], "summary": "Returns if the product is currently available.", "description": "Queries the current availability of a product by chainId, seller and sku.", "parameters": [ { "name": "chainId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "seller", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "502": { "description": "Bad Gateway" }, "508": { "description": "Loop Detected" } } } }, "/inventory/inventory/{chainId}/{seller}/{sku}": { "get": { "tags": [ "InventoryEndpoints" ], "summary": "Returns the inventory count of this product.", "description": "Queries the current inventory of a product by chainId, seller and sku.", "parameters": [ { "name": "chainId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "seller", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sku", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "502": { "description": "Bad Gateway" }, "508": { "description": "Loop Detected" } } } }, "/api/pin": { "post": { "tags": [ "PinEndpoints" ], "summary": "Pin user-authored JSON-LD to IPFS and return its CID", "description": "Accepts raw JSON-LD; verifies payload shape against allowed user-generated models only, stores via IPFS /add + /pin/add, returns { cid } JSON.", "requestBody": { "content": { "application/ld+json; charset=utf-8": { "schema": { "type": "string" } }, "application/json": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "413": { "description": "Content Too Large" } } } }, "/api/pin-media": { "post": { "tags": [ "PinEndpoints" ], "summary": "Pin binary media (e.g. images) to IPFS and return its CID", "description": "Accepts raw binary data (image/*, application/octet-stream); applies the same 8 MiB limit, stores via IPFS /add + /pin/add, returns { cid } JSON.", "requestBody": { "content": { "image/*": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "required": true }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request" }, "413": { "description": "Content Too Large" } } } } }, "components": { "schemas": { "BasketCreateRequest": { "type": "object", "properties": { "operator": { "type": "string", "nullable": true }, "buyer": { "type": "string", "nullable": true }, "chainId": { "type": "integer", "format": "int64", "nullable": true } }, "additionalProperties": false }, "BulkOrderRequest": { "type": "object", "properties": { "orderIds": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false } } }, "tags": [ { "name": "CanonicalizeEndpoints" }, { "name": "CartEndpoints" }, { "name": "Circles.Market.Api" }, { "name": "InventoryEndpoints" }, { "name": "PinEndpoints" } ] }