{ "openapi": "3.1.0", "info": { "title": "Digirare Counterparty Marketplace API", "version": "1.0.0", "description": "The live DIGIRARE HTTP API for Counterparty collectibles on Bitcoin mainnet. Counterparty trades use canonical compact asset IDs, raw quantities are decimal strings, delivery can be attached or detached, and quotes do not reserve inventory. See developer documentation for compatibility and signing rules." }, "servers": [ { "url": "https://api.digirare.com" } ], "tags": [ { "name": "market" }, { "name": "listings" }, { "name": "inventory" }, { "name": "attachments" }, { "name": "checkout" }, { "name": "offers" }, { "name": "auth" }, { "name": "policy-offers", "description": "funded_policy_offer_v1: collection/trait/asset offers any eligible attached one-unit UTXO can accept, co-signed by the market signer." } ], "paths": { "/v1/offer-cancellations/review": { "post": { "operationId": "reviewOfferCancellation", "summary": "Review cancelled offers before wallet unlock", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Authenticated read-only snapshot for wallet cancellation notification. Every offer must belong to the session address and already be cancelled. Returns the offer IDs and distinct funding outpoints with stillCommitted flags; live shared offers or pending settlements keep their coins protected. This endpoint neither unlocks coins nor invalidates Bitcoin signatures.", "requestBody": { "$ref": "#/components/requestBodies/OfferCancellationReview" }, "responses": { "200": { "description": "Cancellation review snapshot", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "object", "required": [ "standard", "action", "offerIds", "coins" ], "properties": { "standard": { "const": "counterparty-marketplace" }, "action": { "const": "cancel_offers" }, "offerIds": { "type": "array", "items": { "type": "string" } }, "coins": { "type": "array", "items": { "type": "object", "required": [ "outpoint", "stillCommitted" ], "properties": { "outpoint": { "type": "object", "required": [ "txid", "vout" ], "properties": { "txid": { "type": "string" }, "vout": { "type": "integer", "minimum": 0 } } }, "stillCommitted": { "type": "boolean" } } } } } } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/artists": { "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum rows in this page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Continuation returned as next_cursor. Keep the same filters between pages." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Substring search; ASCII case-insensitive." }, { "name": "letter", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^([A-Z]|#)?$" }, "description": "First character of the current display name, ASCII case-insensitive. # includes numbers, symbols and names outside A–Z. Omit for all initials." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "name", "artworks" ], "default": "name" }, "description": "Sort by ASCII case-insensitive display name, or descending distinct credited artwork count with name and id as tie-breakers. Keep the same sort between pages." } ], "get": { "operationId": "listArtists", "summary": "Browse artist credits", "tags": [ "market" ], "description": "Browse effective artist credits, including curated corrections. Counts deduplicate assets across collections. Defaults to name order; artworks order can be used for a featured selection. Credits and artwork counts do not verify artist identity.", "responses": { "200": { "$ref": "#/components/responses/ArtistList" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/artists/{key}": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 201 }, "description": "Readable artist slug, or ~ followed by the exact metadata credit, URL-encoded. Ambiguous slugs return 404; exact keys keep distinct credits separate." } ], "get": { "operationId": "getArtist", "summary": "Get an artist catalog", "tags": [ "market" ], "description": "Artwork and collection counts plus public fillable listing count and floor. Pending, private, reserved and unsafe exposed-price listings are excluded from market statistics.", "responses": { "200": { "$ref": "#/components/responses/ArtistDetail" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/artists/{key}/assets": { "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 201 }, "description": "Readable artist slug, or ~ followed by the exact metadata credit, URL-encoded. Ambiguous slugs return 404; exact keys keep distinct credits separate." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 40 }, "description": "Maximum rows in this page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Continuation returned as next_cursor. Keep the same filters between pages." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Substring search; ASCII case-insensitive." }, { "name": "collection", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Optional collection slug." }, { "name": "listed", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" }, "description": "1 restricts results to assets with a public fillable listing." } ], "get": { "operationId": "listArtistAssets", "summary": "Browse an artist’s artworks", "tags": [ "market" ], "description": "Distinct credited assets sorted by asset name. Filters apply to the entire catalog. An asset in several collections appears once, preferring its primary membership among matching credits.", "responses": { "200": { "$ref": "#/components/responses/ArtistAssetList" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/fee-rate": { "get": { "operationId": "getFeeRate", "summary": "Current fee rates", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/FeeRates" }, "502": { "$ref": "#/components/responses/Error" } } } }, "/v1/attach-fee-estimate": { "get": { "operationId": "getAttachFeeEstimate", "summary": "Attach fee estimate (XCP)", "tags": [ "market" ], "description": "Counterparty's current XCP fee for one attach, as a raw XCP quantity. An estimate for display only: consensus charges the fee in force at the block that parses each attach, so it is variable until the attach confirms. It is neither a Bitcoin network fee nor a marketplace fee.", "responses": { "200": { "description": "Current per-attach XCP fee estimate", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "object", "required": [ "xcp_fee_raw", "variable" ], "properties": { "xcp_fee_raw": { "$ref": "#/components/schemas/RawQuantity" }, "variable": { "const": true } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "502": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections": { "get": { "operationId": "listCollections", "summary": "List collections", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/CollectionList" } } } }, "/v1/search": { "get": { "operationId": "search", "summary": "Search assets and collections", "tags": [ "market" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free text: collection name or slug, asset name, or subasset longname prefix. Empty returns the leading collections.", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "$ref": "#/components/responses/SearchResults" }, "400": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}": { "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "getCollection", "summary": "Get a collection", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/CollectionDetail" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}/assets": { "parameters": [ { "$ref": "#/components/parameters/Slug" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 80 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque continuation token returned as next_cursor. Valid only with the order and filters it was issued under.", "schema": { "type": "string" } }, { "name": "order", "in": "query", "required": false, "description": "Omitted: listed assets first, cheapest floor first, then the collection sequence. `catalog`: the collection's own sequence (series, card, protocol ordinal, issuance block, issuance year, asset) with no listed-first step; floors and offers are still returned.", "schema": { "type": "string", "enum": [ "catalog" ] } }, { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring of the asset name or subasset longname, at most 80 characters.", "schema": { "type": "string", "maxLength": 80 } }, { "name": "min_price_sats", "in": "query", "required": false, "description": "Lowest floor price to include; excludes unlisted assets.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "max_price_sats", "in": "query", "required": false, "description": "Highest floor price to include; excludes unlisted assets.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "series", "in": "query", "required": false, "style": "form", "explode": true, "description": "Repeatable. Any listed series matches.", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0 } } }, { "name": "supply", "in": "query", "required": false, "style": "form", "explode": true, "description": "Repeatable supply bucket key. Any listed bucket matches.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSupplyBucket" } } }, { "name": "trait", "in": "query", "required": false, "style": "form", "explode": true, "description": "Repeatable `name:value` editorial trait. Values under one name are alternatives; different names all have to match. At most 20 series, supply and trait terms together.", "schema": { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 301 } } } ], "get": { "operationId": "listCollectionAssets", "summary": "List a collection’s assets", "tags": [ "market" ], "description": "Paged collection assets. Listed assets sort first by price; remaining inventory sorts by series, card, protocol ordinal, and issuance. Filters narrow that same order, so a cursor is valid only with the filters it was issued under.", "responses": { "200": { "$ref": "#/components/responses/CollectionAssetList" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}/facets": { "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "getCollectionFacets", "summary": "Collection browse facets", "tags": [ "market" ], "description": "Collection-wide counts behind the browse rail: series, supply bucket, and editorial trait values. Counts cover the whole collection, not the current filter intersection. Trait names appear only with two to forty distinct values; Artist, Series and Card are carried as columns and never as trait facets.", "responses": { "200": { "$ref": "#/components/responses/CollectionFacets" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}/book": { "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "getCollectionBook", "summary": "Collection order book", "tags": [ "market", "offers" ], "description": "Bounded collection trading workspace with ask depth, listing rows, exact-policy offer depth, individual offers, and recent fills. funded_slots counts distinct bid UTXOs within one level; shared slots may appear in multiple alternative policy levels and are never summed into cross-level capacity.", "responses": { "200": { "$ref": "#/components/responses/CollectionBook" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}/holders": { "parameters": [ { "$ref": "#/components/parameters/Slug" }, { "$ref": "#/components/parameters/Limit" } ], "get": { "operationId": "getCollectionHolders", "summary": "Collection holders", "tags": [ "market" ], "description": "Top collection holders across detached address balances and UTXO-attached balances controlled by the same address.", "responses": { "200": { "$ref": "#/components/responses/CollectionHolders" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}/offer-targets": { "parameters": [ { "$ref": "#/components/parameters/Slug" }, { "name": "max_supply_units", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "min_supply_units", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "issued_year", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "series", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "artist", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 8 } } ], "get": { "operationId": "listCollectionOfferTargets", "summary": "Listings a collection offer can target", "tags": [ "offers" ], "description": "Returns a bounded cheapest-first snapshot of currently listed asset outpoints matching the same normalized collection policy predicates enforced during exact authorization. Future listings require a new authorization snapshot.", "responses": { "200": { "$ref": "#/components/responses/CollectionOfferTargets" }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/assets/{asset}": { "parameters": [ { "$ref": "#/components/parameters/AssetReadIdentity" } ], "get": { "operationId": "getAsset", "summary": "Get an asset", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/AssetDetail" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/assets/{asset}/book": { "parameters": [ { "$ref": "#/components/parameters/AssetReadIdentity" } ], "get": { "operationId": "getAssetBook", "summary": "Asset order book", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/AssetBook" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-summaries": { "parameters": [ { "name": "assets", "in": "query", "required": true, "description": "Comma-separated canonical compact asset ids, 1 to 200. A holder with more assets batches requests.", "schema": { "type": "string", "minLength": 3 } }, { "name": "exclude_bidder", "in": "query", "required": false, "description": "Drop this address's own bids, so a seller's holdings view never shows their own offer.", "schema": { "$ref": "#/components/schemas/BitcoinAddress" } } ], "get": { "operationId": "listOfferSummaries", "summary": "Best offers by asset", "tags": [ "market" ], "description": "Best live individual (asset-scope) offer and best live collection or trait policy each listed asset satisfies, with best_offer the higher of the two (the individual offer on a tie). Assets with no live offer are omitted. Each pick is a bounded best-first index walk per asset. Says nothing about whether a particular seller can accept now: that requires an exact authorization on one of their units (GET /v1/address/{address}/exact-offers).", "responses": { "200": { "$ref": "#/components/responses/OfferSummaries" }, "400": { "$ref": "#/components/responses/Error" } } } }, "/v1/listings": { "get": { "operationId": "listFreshListings", "summary": "Newest listings", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/ListingList" } } } }, "/v1/address/{address}/listings": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listSellerListings", "summary": "An address’s public listings", "tags": [ "market" ], "description": "Public address storefront. Private counteroffers are excluded.", "responses": { "200": { "$ref": "#/components/responses/SellerListingList" } } } }, "/v1/address/{address}/managed-listings": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listManagedSellerListings", "summary": "Your listings and counters", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Private owner view containing public listings and bidder-scoped counters for management.", "responses": { "200": { "$ref": "#/components/responses/SellerListingList" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/events": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listOwnerEvents", "summary": "Your event feed", "tags": [ "market" ], "security": [ { "session": [] } ], "description": "Private owner feed of what happened to this address's orders, newest first: listings filled/delisted/expired/invalidated (as seller), offers accepted/cancelled/expired/retired and exact authorizations used/retired (as bidder), collection offers filled/cancelled/expired/retired (as bidder), and settlements the market saw confirm (as buyer by delivery address, or as seller). Merged from several sources under one opaque keyset cursor; follow next_cursor. An event's `at` is when the market observed it (a derived expiry: its expires_at), so new events arrive at the head. Dedupe on event_id and re-read a short overlap window when polling. Carries ids, txids and integer-sat prices, never a PSBT or raw transaction.", "responses": { "200": { "$ref": "#/components/responses/OwnerEventList" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/ended-listings": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listEndedSellerListings", "summary": "Your recently ended listings", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Private owner view of listings that ended in the last 30 days, newest end first, each with a reason derived from stored market facts.", "responses": { "200": { "$ref": "#/components/responses/EndedListingList" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/events": { "parameters": [ { "name": "kind", "in": "query", "required": false, "description": "Narrow the feed to one family: sales, listings (listed and delisted), or offers (asset and collection offers placed and ended).", "schema": { "type": "string", "enum": [ "sales", "listings", "offers" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listMarketEvents", "summary": "Market activity", "tags": [ "market" ], "description": "Public feed of the whole market, newest first: sales (the /fills tape, with its exclusions), listings placed and delisted/expired/invalidated, and asset and collection offers placed and ended. A filled listing or offer has no separate ended event; its sale is the event. Merged from several sources under one opaque keyset cursor; follow next_cursor. Public book facts only: never a PSBT, a signature, a private counter, or a raw transaction.", "responses": { "200": { "$ref": "#/components/responses/MarketEventList" }, "400": { "$ref": "#/components/responses/Error" } } } }, "/v1/fills": { "parameters": [ { "name": "collection", "in": "query", "required": false, "description": "Narrow the feed to one curated collection slug.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listRecentFills", "summary": "Recent sales", "tags": [ "market" ], "responses": { "200": { "$ref": "#/components/responses/FillList" }, "400": { "$ref": "#/components/responses/Error" } } } }, "/v1/listings/{id}/reprice": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "repriceListing", "summary": "Reprice a listing", "description": "Requires a current session for the operation owner before looking up the private resource; missing and foreign IDs return the same 404. Rate limited as a signed completion: 120 per minute per session address (or IP when anonymous), 600 per IP across sessions, retries of identical signed bytes still count and must honor 429 and Retry-After; a limiter outage does not block it.", "tags": [ "listings" ], "requestBody": { "$ref": "#/components/requestBodies/SignedPsbt" }, "responses": { "200": { "description": "Successful repriceListing response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireListingRepriceResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ] } }, "/v1/listings/{id}/reprice-preflight": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "createListingRepricePreflight", "summary": "Prepare a listing reprice", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Returns a fresh wallet-reviewable listing authorization for the same prepared asset UTXO at a new price. No attach or Bitcoin transaction is required. Rate limited as an expensive write (20 per minute per session address, or per IP when anonymous; 120 per IP across sessions).", "requestBody": { "$ref": "#/components/requestBodies/RepricePreflight" }, "responses": { "200": { "$ref": "#/components/responses/ListingRepricePreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listings/{id}/delist": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "delistListing", "summary": "Delist a listing", "tags": [ "listings" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Successful delistListing response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireListingDelistResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listings/batch": { "post": { "operationId": "listingBatch", "summary": "Reprice or delist up to 20 listings", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "The batch form of the per-listing owner actions (whose routes and contracts are unchanged): 1..20 distinct listings, every one sold by the session address, ownership checked for every item before anything is composed or written. `reprice_preflight` runs the single reprice preflight's checks per item and returns only freshly built UNSIGNED templates (never a stored signature); any refused item refuses the batch (the first refusal sets the status and code, `refused_listings` lists every refused item); it reserves nothing. `reprice` verifies every signed listing PSBT exactly as POST /v1/listings/{id}/reprice before anything is written, refusing the batch on any failure, then writes the single path's guarded updates in one D1 batch; each overwrites the superseded seller half in the same statement, and a listing a buyer claimed between verification and write keeps its old price and is reported `ok: false` with `state_changed` (the single path's 409). `delist` needs no signature and wipes each stored half in the delisting statement; a missing or foreign listing refuses the whole batch, and a listing no longer active is reported `ok: false`. Rate limited as an expensive write.", "requestBody": { "$ref": "#/components/requestBodies/ListingBatch" }, "responses": { "200": { "description": "reprice_preflight: templates in request order; reprice and delist: per-listing outcomes in request order", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ListingRepricePreflightBatchEnvelope" }, { "$ref": "#/components/schemas/ListingBatchOutcomesEnvelope" } ] } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/transactions/{txid}/attach": { "get": { "operationId": "getAttachTransactionStatus", "summary": "Attach transaction status", "tags": [ "attachments" ], "description": "On-demand Bitcoin confirmation and Counterparty attach parse status. Stateless and uncached; an upstream failure is not a missing or invalid transaction.", "parameters": [ { "name": "txid", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Txid" } } ], "responses": { "200": { "description": "Attachment observation", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "additionalProperties": false, "properties": { "result": { "oneOf": [ { "type": "object", "required": [ "state" ], "additionalProperties": false, "properties": { "state": { "enum": [ "not_found", "pending_bitcoin", "pending_indexer" ] } } }, { "type": "object", "required": [ "state", "xcp_fee_actual_raw" ], "additionalProperties": false, "properties": { "state": { "const": "valid" }, "xcp_fee_actual_raw": { "$ref": "#/components/schemas/RawQuantity" } } }, { "type": "object", "required": [ "state", "reason" ], "additionalProperties": false, "properties": { "state": { "const": "invalid" }, "reason": { "type": "string" } } } ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/transactions/status": { "post": { "operationId": "getTransactionStatuses", "summary": "Transaction statuses", "tags": [ "attachments" ], "description": "Read-only Bitcoin existence checks for at most 25 unique txids, in request order. At most four upstream reads run concurrently. No raw transactions, balances, broadcast or D1 writes. Unknown is never not_found; confirmed is Bitcoin confirmation only, not Counterparty validity. Rate-limited and no-store.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txids" ], "additionalProperties": false, "properties": { "txids": { "type": "array", "minItems": 1, "maxItems": 25, "uniqueItems": true, "items": { "$ref": "#/components/schemas/Txid" } } } } } } }, "responses": { "200": { "description": "Ordered Bitcoin observations", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "additionalProperties": false, "properties": { "result": { "type": "array", "maxItems": 25, "items": { "oneOf": [ { "type": "object", "required": [ "txid", "state", "confirmed" ], "additionalProperties": false, "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "state": { "const": "known" }, "confirmed": { "type": "boolean" }, "confirmations": { "type": "integer", "minimum": 0, "description": "Bitcoin confirmations at the server's canonical tip, read once after every lookup. Absent when unconfirmed or the tip is unknown." }, "final": { "type": "boolean", "description": "At least FINALITY_DEPTH (3) confirmations deep. False when unconfirmed, shallower, or the tip is unknown; a client leg runner keeps declaring a non-final attach in flight." } } }, { "type": "object", "required": [ "txid", "state" ], "additionalProperties": false, "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "state": { "enum": [ "not_found", "unknown" ] } } } ] } } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/transactions/inspect": { "post": { "operationId": "inspectTransaction", "summary": "Inspect signed transaction bytes", "tags": [ "attachments" ], "description": "Read-only recovery of exact signed bytes, limited to 16 inputs. Checks Bitcoin transaction status and funding outspends. Never relays or writes D1. A pending conflicting spend or missing parent is not cancellation evidence.", "requestBody": { "$ref": "#/components/requestBodies/RelayTransaction" }, "responses": { "200": { "$ref": "#/components/responses/TransactionRecovery" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/transactions": { "post": { "operationId": "relayTransaction", "summary": "Relay a signed transaction", "tags": [ "attachments" ], "description": "Relays a transaction the browser finalized itself (a preparation leg) through the marketplace broadcaster. Stateless: nothing is journaled; the response is the txid the network echoed.", "requestBody": { "$ref": "#/components/requestBodies/RelayTransaction" }, "responses": { "200": { "$ref": "#/components/responses/TransactionRelay" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/attach-templates": { "post": { "operationId": "composeAttachTemplate", "summary": "Compose an attach", "tags": [ "attachments" ], "security": [ { "session": [] } ], "description": "Composes and independently verifies one one-unit attach for the client leg runner. Nothing is stored or reserved: the browser signs, broadcasts, and keeps its own leg state, and the marketplace learns about the asset UTXO when Counterparty indexes it. Explicit funding lets a leg name a disjoint coin or the previous leg's unconfirmed change.", "requestBody": { "$ref": "#/components/requestBodies/ComposeAttachTemplate" }, "responses": { "200": { "$ref": "#/components/responses/AttachTemplate" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/attach-templates/speed-up": { "post": { "operationId": "quoteAttachSpeedUp", "summary": "Speed up an unconfirmed attach", "tags": [ "attachments" ], "security": [ { "session": [] } ], "description": "Returns an unsigned CPFP child for the session owner's own unconfirmed attach. The server reads the attach from Bitcoin, proves from its bytes that it is a Counterparty attach whose unit lands on its first spendable output, finds the owner's change output after it (never the asset UTXO), checks that the change is unspent, and sizes a one-input, one-output child back to the same owner so the package (the attach, its unconfirmed ancestors, and the child) reaches fee_rate (default: the next-block rate). Nothing is stored. Sign input 0 with DEFAULT|ALL and relay the finalized child with POST /transactions. Refusals carry a reason: confirmed, no_change, change_spent (with spent_by), fee_sufficient, ancestor_limit, not_attach, or insufficient_change (code insufficient_funds with need_sats, have_sats and shortfall_sats).", "requestBody": { "$ref": "#/components/requestBodies/QuoteAttachSpeedUp" }, "responses": { "200": { "$ref": "#/components/responses/AttachSpeedUp" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights": { "post": { "operationId": "createListingPreflight", "summary": "Start a listing", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Reuses an eligible attached UTXO or returns a server-verified Counterparty attach PSBT. When a price is supplied, the response also contains the exact dependent listing template for a one-review attach-and-list flow.", "requestBody": { "$ref": "#/components/requestBodies/CreateListingPreflight" }, "responses": { "201": { "$ref": "#/components/responses/ListingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/listing-preflights": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "state", "in": "query", "required": false, "description": "in_flight returns only the seller's signed attaches still confirming (broadcasting or awaiting the indexer), newest activity first, at most 50, without paging; limit and cursor are ignored.", "schema": { "type": "string", "enum": [ "in_flight" ] } } ], "get": { "operationId": "listSellerListingPreflights", "summary": "Your listing drafts", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Owner operation history for recovering a lost preflight-create response. An unsigned attach past its expiry is reported as expired at read time.", "responses": { "200": { "description": "Successful listSellerListingPreflights response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireListingPreflightResult" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getListingPreflight", "summary": "Get a listing draft", "tags": [ "listings" ], "security": [ { "session": [] } ], "responses": { "200": { "$ref": "#/components/responses/ListingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights/{id}/attach": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "submitListingAttach", "summary": "Submit a signed attach", "description": "Rate limited as a signed completion: 120 per minute per session address (or IP when anonymous), 600 per IP across sessions, retries of identical signed bytes still count and must honor 429 and Retry-After; a limiter outage does not block it.", "tags": [ "listings" ], "security": [ { "session": [] } ], "requestBody": { "$ref": "#/components/requestBodies/SignedPsbt" }, "responses": { "202": { "$ref": "#/components/responses/ListingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights/{id}/discard": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "discardListingPreflight", "summary": "Discard a listing draft", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Discards a listing draft in either mode when no signed attach is in flight: an unsigned attach, a prepared or priced draft, or a failed or expired operation. A settled attach stays attached as ordinary prepared inventory, and any waiting dependent listing authorization is cancelled. Refused with 409 while a signed attach is broadcasting or awaiting the indexer, and for a completed listing (delist it instead). Idempotent; concurrent submission and discard are arbitrated atomically.", "responses": { "200": { "$ref": "#/components/responses/ListingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights/{id}/price": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "priceListingPreflight", "summary": "Price a listing draft", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Binds or replaces the price on prepared inventory and returns the exact unsigned listing authorization.", "requestBody": { "$ref": "#/components/requestBodies/RepricePreflight" }, "responses": { "200": { "$ref": "#/components/responses/ListingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights/{id}/attach-and-list": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "submitAttachAndListing", "summary": "Submit attach and listing together", "tags": [ "listings" ], "security": [ { "session": [] } ], "description": "Journals one signed attach and its signed dependent listing. Only the attach broadcasts immediately; the listing becomes public after Bitcoin and Counterparty verification. Rate limited as a signed completion: 120 per minute per session address (or IP when anonymous), 600 per IP across sessions, retries of identical signed bytes still count and must honor 429 and Retry-After; a limiter outage does not block it.", "requestBody": { "$ref": "#/components/requestBodies/SignedAttachAndListing" }, "responses": { "202": { "$ref": "#/components/responses/ListingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/listing-preflights/{id}/listing": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "finalizeListingPreflight", "summary": "Submit the listing signature", "description": "Rate limited as a signed completion: 120 per minute per session address (or IP when anonymous), 600 per IP across sessions, retries of identical signed bytes still count and must honor 429 and Retry-After; a limiter outage does not block it.", "tags": [ "listings" ], "security": [ { "session": [] } ], "requestBody": { "$ref": "#/components/requestBodies/FinalListing" }, "responses": { "200": { "description": "Successful finalizeListingPreflight response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireListingResult" } } } } } }, "201": { "description": "Successful finalizeListingPreflight response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireListingResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/fills/request": { "post": { "operationId": "requestFill", "summary": "Quote a purchase", "tags": [ "checkout" ], "description": "Returns a 180-second, non-reserving PSBT snapshot. Detached delivery is the default; a one-unit purchase may instead preserve the asset on its own buyer-owned asset UTXO. Public cart quotes may be requested without a session. A counter_id requires a current session matching buyer_address; foreign and missing counters return the same 404.", "requestBody": { "$ref": "#/components/requestBodies/FillRequest" }, "responses": { "201": { "$ref": "#/components/responses/FillQuote" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "security": [ {}, { "session": [] } ] } }, "/v1/fills/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getFillStatus", "summary": "Purchase status", "tags": [ "checkout" ], "security": [ { "session": [] } ], "description": "Private durable operation status for response-loss recovery; never exposes raw settlement bytes or seller PSBTs.", "responses": { "200": { "description": "Successful getFillStatus response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireFillStatusResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/fills/complete": { "post": { "operationId": "completeFill", "summary": "Complete a purchase", "tags": [ "checkout" ], "description": "Requires a current session for the operation owner before looking up the private resource; missing and foreign IDs return the same 404. Verifies byte-exact template equality and every buyer funding signature before atomically claiming listings, journaling exact final bytes, and broadcasting. Rate limited as a signed completion: 120 per minute per session address (or IP when anonymous), 600 per IP across sessions, retries of identical signed bytes still count and must honor 429 and Retry-After; a limiter outage does not block it.", "requestBody": { "$ref": "#/components/requestBodies/CompleteFill" }, "responses": { "200": { "description": "Successful completeFill response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireFillCompletionResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ] } }, "/v1/offers": { "post": { "operationId": "placeOffers", "summary": "Place offers on bid outputs", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Production requires a session proving control of the shared bid-output address; funding alone is not accepted as identity.", "requestBody": { "$ref": "#/components/requestBodies/PlaceOffers" }, "responses": { "201": { "description": "Successful placeOffers response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireOfferPlacementResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-funding-preflights": { "post": { "operationId": "preflightOfferFunding", "summary": "Check an offer funding coin", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Checks that one exact-value P2WPKH/P2TR funding outpoint is unspent, asset-free, and owned by the authenticated bidder before any offer policy is written.", "requestBody": { "$ref": "#/components/requestBodies/OfferFundingPreflight" }, "responses": { "200": { "$ref": "#/components/responses/OfferFundingPreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-acceptance-selections/validate": { "post": { "operationId": "validateOfferAcceptanceSelection", "summary": "Validate a bulk offer acceptance", "tags": [ "offers" ], "description": "Non-reserving guard for a seller bulk action. Rejects multiple policy ids backed by the same bid outpoint with code duplicate_funding_slot; one distinct funding_slot_id equals one possible fill. Rate limited as an expensive write (20 per minute per session address, or per IP when anonymous; 120 per IP across sessions).", "requestBody": { "$ref": "#/components/requestBodies/ValidateOfferAcceptanceSelection" }, "responses": { "200": { "description": "Successful validateOfferAcceptanceSelection response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireOfferAcceptanceSelectionResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/offers": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listBidderOffers", "summary": "Your offers", "tags": [ "offers" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Successful listBidderOffers response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireBidderOffer" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/offer-coverage": { "parameters": [ { "$ref": "#/components/parameters/Address" } ], "get": { "operationId": "listBidderOfferCoverage", "summary": "Your offers that could cover more listings", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "For the bidder's newest 50 live offers, returns each offer whose policy matches current public listings that its funding slot has not authorized yet, as { offer_id, uncovered, more }. uncovered is capped at 8 (one wallet prompt); more is true when at least one further listing is uncovered. Offers with nothing uncovered are omitted. Owner-only; one read replaces a per-offer authorization-targets probe.", "responses": { "200": { "description": "Successful listBidderOfferCoverage response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireOfferCoverageSummary" } }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offers/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "cancelOffer", "summary": "Cancel an offer", "tags": [ "offers" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Successful cancelOffer response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireOfferCancelResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-placements/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "cancelOfferPlacement", "summary": "Cancel a bulk offer", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Cancels every still-active offer policy created by the placement. A funding outpoint remains protected if another placement still has a live policy over it; signed acceptances remain in their own lifecycle.", "responses": { "200": { "description": "Successful cancelOfferPlacement response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireOfferPlacementCancelResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-slot-releases": { "post": { "operationId": "composeOfferSlotRelease", "summary": "Release offer funds", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Release funds for exact offers: an unsigned self-send of the session owner's own bid slots (live or ended) back to the owner's own script, the cancel Bitcoin enforces. Spending a slot retires every offer and exact authorization on it once the outspend poller sees it. Every value is read from the chain; nothing is stored or reserved. The result lists `slots` in the PSBT's input order with `expected_txid`, `fee_sats`, `output_sats`, and signer instructions; the wallet side proves the PSBT spends exactly those slots into one output paying the owner before signing, then relays through `POST /v1/transactions`. A slot a signed acceptance is settling answers 409 `state_changed`; a spent slot answers 409 `conflict_spend`.", "requestBody": { "$ref": "#/components/requestBodies/OfferSlotRelease" }, "responses": { "200": { "description": "Successful composeOfferSlotRelease response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireOfferSlotReleaseResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offers/{id}/exact-authorizations": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "createExactOfferAuthorization", "summary": "Authorize an exact offer", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Buyer composes an exact-target transaction over a known asset outpoint. Nothing is reserved; the returned input-0 ALL signature request becomes a unilateral seller-executable authorization only after bidder-psbt submission. expires_at is a marketplace serving deadline, not Bitcoin signature expiry; spending the shared funding outpoint is the on-chain invalidation mechanism. The seller read endpoint requotes current fees and, when necessary, supplies a seller-funded CPFP child. The seller is the taker: platform_fee_sats is the fee output platformFeeSats(price_sats), prefunded_fee_sats is the part a legacy bidder-pays slot already funded (0 for every new offer), and seller_proceeds_sats = price_sats + asset UTXO - (platform_fee_sats - prefunded_fee_sats) - network_fee_sats. platform_fee_internal_key (see the PlatformFeeInternalKey schema) is the fee output's x-only Taproot internal key, derived server-side, on this and every exact-authorization template response (batch and seller read).", "requestBody": { "$ref": "#/components/requestBodies/AcceptOffer" }, "responses": { "201": { "description": "Successful createExactOfferAuthorization response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferAuthorizationResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offers/{id}/exact-authorizations/batch": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "createExactOfferAuthorizationBatch", "summary": "Authorize exact offers in bulk", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Atomically preflights and stores 1..100 known asset-outpoint alternatives over one shared funding slot. Any invalid or duplicate target rejects the entire new batch; nothing reserves funding. exact_offer_v1 is an explicit-outpoint snapshot: newly discovered matching listings are not automatically authorized and require a new authorization batch/buyer signature.", "requestBody": { "$ref": "#/components/requestBodies/ExactAuthorizationBatch" }, "responses": { "201": { "description": "Successful createExactOfferAuthorizationBatch response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferAuthorizationBatchResult" }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offers/{id}/authorization-targets": { "parameters": [ { "$ref": "#/components/parameters/Id" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 8 } } ], "get": { "operationId": "listOfferAuthorizationTargets", "summary": "Listings your offer can target", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Returns the offer owner a cheapest-first list of current public listings that the live offer policy matches but its funding slot cannot yet settle unilaterally: no active or settling authorization over the slot, excluding the bidder's own listings. Pass the outpoints to the authorization batch; the batch reuses this offer's own still-unsigned rows for any target it already prepared.", "responses": { "200": { "description": "Successful listOfferAuthorizationTargets response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WirePublicListing" } }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/exact-offer-authorizations/{id}/bidder-psbt": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "submitExactOfferBidderPsbt", "summary": "Submit the buyer’s offer signature", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Verifies the buyer's DEFAULT/ALL signature on Counterparty input 0 and activates the immutable exact authorization. Rate limited as a signed completion: 120 per minute per session address (or IP when anonymous), 600 per IP across sessions, retries of identical signed bytes still count and must honor 429 and Retry-After; a limiter outage does not block it.", "requestBody": { "$ref": "#/components/requestBodies/SignedPsbt" }, "responses": { "200": { "description": "Successful submitExactOfferBidderPsbt response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferActivationResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/exact-offer-authorizations/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getExactOfferAuthorization", "summary": "Get an exact offer to accept", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Private to the named seller (session required). Returns the UNSIGNED settlement template, the input-1 seller signing instruction, and the economics a wallet verifies. The buyer signature is never served: the seller signs input 1 with DEFAULT|ALL over the template and the market merges the stored buyer signature server-side on accept. The buyer does not need to return. Carries platform_fee_internal_key (PlatformFeeInternalKey) when the fee output's key can be derived.", "responses": { "200": { "description": "Successful getExactOfferAuthorization response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferAuthorizationResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/exact-offer-authorizations/{id}/counter-preflight": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "createCounterPreflight", "summary": "Prepare a counteroffer", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Builds a seller-reviewable private listing authorization for the exact asset UTXO covered by a live bidder authorization. The counter price must be at least 1,000 sats above the offer, a multiple of 1,000, and at least 5,000 sats (422 counter_price_invalid carries minimum_counter_sats), and cannot outlive the offer.", "requestBody": { "$ref": "#/components/requestBodies/RepricePreflight" }, "responses": { "200": { "description": "Successful createCounterPreflight response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireCounterPreflightResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/exact-offer-authorizations/{id}/counter": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "createCounterFromAuthorization", "summary": "Submit a counteroffer", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Verifies and stores the seller's private listing signature. Repeating the same authorization, target, and price is idempotent after response loss.", "requestBody": { "$ref": "#/components/requestBodies/SignedPsbt" }, "responses": { "200": { "description": "Successful createCounterFromAuthorization response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireCounterListingResult" } } } } } }, "201": { "description": "Successful createCounterFromAuthorization response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireCounterListingResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/exact-offer-authorizations/{id}/status": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getExactOfferAcceptanceStatus", "summary": "Exact offer status", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Private bidder/seller lifecycle and settlement status for response-loss recovery. Signed PSBT and raw transaction bytes are omitted.", "responses": { "200": { "description": "Successful getExactOfferAcceptanceStatus response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferAcceptanceStatusResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/exact-offer-authorizations/{id}/accept": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "acceptExactOfferAuthorization", "summary": "Accept an exact offer", "tags": [ "offers" ], "description": "Requires a current session for the operation owner before looking up the private resource; missing and foreign IDs return the same 404. Verifies the seller's parent signature and any required seller-funded CPFP child, atomically claims the shared funding slot and asset outpoint, journals exact parent/child bytes, and submits the settlement without a bidder callback. Signed-completion rate limit: 120 per session address and 600 per IP per minute, fail open during limiter outages; session and signature checks still apply.", "requestBody": { "$ref": "#/components/requestBodies/SignedExactAccept" }, "responses": { "200": { "description": "Successful acceptExactOfferAuthorization response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferAcceptanceResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } }, "security": [ { "session": [] } ] } }, "/v1/exact-offer-authorizations/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "cancelExactOfferAuthorization", "summary": "Cancel an exact offer", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Revokes marketplace access. Before the buyer signs, this also invalidates the incomplete authorization. After activation, already-disclosed Bitcoin signature bytes cannot be revoked; the response marks funding_spend_required and identifies the shared funding outpoint whose spend invalidates this authorization and every sibling.", "responses": { "200": { "description": "Successful cancelExactOfferAuthorization response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireExactOfferAuthorizationCancellationResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/asset-utxos/{txid}/{vout}/exact-offers": { "parameters": [ { "name": "txid", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Txid" } }, { "name": "vout", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 } } ], "get": { "operationId": "listExactOffersForAssetUtxo", "summary": "Offers on an asset UTXO", "tags": [ "offers" ], "description": "Lists live buyer-authorized offers the current holder can accept unilaterally. Each funding_slot_id is capacity one.", "responses": { "200": { "description": "Successful listExactOffersForAssetUtxo response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireExactOfferSummary" } }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/counters": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listBidderCounters", "summary": "Counteroffers to you", "tags": [ "offers" ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Successful listBidderCounters response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireCounterOffer" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/in-flight-purchases": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listInFlightPurchases", "summary": "Your purchases in flight", "tags": [ "checkout" ], "security": [ { "session": [] } ], "description": "Session owner only. The buyer's purchases whose exact signed bytes the server has journaled and Bitcoin has not confirmed: prepared (not yet seen by the network; the server keeps relaying the recorded bytes and new quotes never spend their coins) or broadcast (waiting for a block). Each row carries fill_id, txid, status, delivery_mode, the cart or counter intent, listing_ids (the listings this purchase takes, so a page can show them as the buyer's own and pending before the public book catches up), and created_at. Keyset-paginated newest first.", "responses": { "200": { "description": "Successful listInFlightPurchases response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireInFlightPurchase" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/inventory/attachable": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/CollectionFilter" }, { "$ref": "#/components/parameters/AssetFilter" } ], "get": { "operationId": "listAttachableInventory", "summary": "Your attachable inventory", "tags": [ "inventory" ], "description": "Curated address-level Counterparty balances that can be attached for listing. Public, and edge-cached for 10 seconds under its own `collection` and `asset` parameters: detached balances move only when the indexer applies a block. The prepared-inventory read is never cached.", "responses": { "200": { "description": "Successful listAttachableInventory response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireAttachableAssetResult" } }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/exact-offers": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listSellerExactOffers", "summary": "Offers on your units", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Private paginated seller inbox of live buyer-authorized offers, returned in one indexed read instead of one request per asset outpoint. Each row carries offer_scope: asset for an individual bid, collection for a collection or trait policy.", "responses": { "200": { "description": "Successful listSellerExactOffers response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireSellerExactOfferSummary" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/exact-acceptances": { "parameters": [ { "$ref": "#/components/parameters/Address" } ], "get": { "operationId": "listSellerExactAcceptances", "summary": "Your acceptances settling", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Private seller view of the offer acceptances the server still owns: claimed but not yet broadcast (claiming or prepared), broadcast and awaiting confirmation, and real losses (conflicted or dropped) from the last day. Confirmed acceptances leave the set. A bounded status read capped at 50 rows, not a paginated history. The browser keeps no acceptance record; the funding claim and the settlement journal are what refuse a second seller signature.", "responses": { "200": { "description": "Successful listSellerExactAcceptances response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WireSellerExactAcceptance" } }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/inventory/prepared": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/CollectionFilter" }, { "$ref": "#/components/parameters/AssetFilter" } ], "get": { "operationId": "listPreparedInventory", "summary": "Your prepared inventory", "tags": [ "inventory" ], "description": "Curated exact one-unit attached outpoints available for listing.", "responses": { "200": { "description": "Successful listPreparedInventory response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WirePreparedAssetResult" } }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/auth/session": { "post": { "operationId": "createSessionFromProof", "summary": "Sign in with a connection proof", "description": "Rate limited per IP: 60 per minute, whether or not a session is presented.", "tags": [ "auth" ], "requestBody": { "$ref": "#/components/requestBodies/ConnectionProof" }, "responses": { "200": { "$ref": "#/components/responses/MarketplaceSession" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/auth/challenge": { "post": { "operationId": "createAuthChallenge", "summary": "Get a sign-in challenge", "description": "Rate limited per IP: 60 per minute, whether or not a session is presented.", "tags": [ "auth" ], "requestBody": { "$ref": "#/components/requestBodies/AddressOnly" }, "responses": { "200": { "$ref": "#/components/responses/AuthChallenge" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/auth/verify": { "post": { "operationId": "verifyAuthChallenge", "summary": "Sign in with a signed challenge", "description": "Rate limited per IP: 60 per minute, whether or not a session is presented.", "tags": [ "auth" ], "requestBody": { "$ref": "#/components/requestBodies/ChallengeProof" }, "responses": { "200": { "$ref": "#/components/responses/MarketplaceSession" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-funding-templates": { "post": { "operationId": "composeOfferFundingTemplate", "summary": "Compose offer funding", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Composes the bidder's self-send that mints `slot_count` independent bid outputs from their own asset-free P2WPKH/P2TR inputs, plus change. Detached slots equal `price_sats`; attached-delivery slots include an additional 330 sat buyer-owned asset UTXO. Returns the unsigned template with signer instructions. Nothing is stored or reserved: the browser signs, finalizes, and hands the bytes to `POST /v1/funded-offers`. Coins an earlier leg of the same run already spent are passed back in `exclude`.", "requestBody": { "$ref": "#/components/requestBodies/OfferFundingTemplate" }, "responses": { "200": { "$ref": "#/components/responses/OfferFundingTemplate" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/offer-funding-authorization-templates": { "post": { "operationId": "composeOfferFundingAuthorizationTemplates", "summary": "Compose offer authorizations before funding", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Exact-offer authorization templates (1..7 targets) over one set-aside output (`slot_vout`) of an UNSIGNED offer funding template from `POST /v1/offer-funding-templates`, so one wallet review can sign the funding and these authorizations together (the `fund-and-authorize-offers` wallet bundle). Every funding input must be a witness input of the authenticated bidder, so signing cannot change the txid the authorizations spend. Each target is composed exactly as `POST /v1/offers/{id}/exact-authorizations/batch` composes it, at the one returned `fee_rate`, including the asset-UTXO depth rule; `assets` are the placement's asset-scope targets and every target must be one of them. Nothing is stored, placed, or reserved, and `authorization_id` values are preview ids. After signing, place the offer with the signed funding (`POST /v1/funded-offers`), create the batch with `fee_rate` set to this response's rate, and submit each signature whose `expected_txid` the batch reproduced; a template that no longer reproduces is signed again.", "requestBody": { "$ref": "#/components/requestBodies/FundedAuthorizationTemplates" }, "responses": { "200": { "description": "Successful composeOfferFundingAuthorizationTemplates response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "$ref": "#/components/schemas/WireFundedAuthorizationTemplatesResult" }, "result_count": { "type": "integer", "minimum": 0 } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/funded-offers": { "post": { "operationId": "placeFundedOffers", "summary": "Place funded offers", "tags": [ "offers" ], "security": [ { "session": [] } ], "description": "Places offers on bid outputs the signed funding transaction itself proves. Each named output must pay the session's own address and hold exactly the offer price (plus the 330-sat asset UTXO for attached delivery); the accepting seller pays the marketplace fee. The placement is rehearsed first so a bad target fails before the network sees anything; the bytes are then relayed (a transaction the network already knows is a success) and the cross-product of the outputs and `targets` is placed. A relay failure places nothing and journals nothing; the client submits the same bytes again.", "requestBody": { "$ref": "#/components/requestBodies/FundedOffers" }, "responses": { "201": { "description": "Successful placeFundedOffers response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireFundedOfferPlacementResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-offers/preflight": { "post": { "operationId": "preflightPolicyOffer", "summary": "Prepare a collection offer", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "Selects (or verifies) the bidder's confirmed, asset-free funding inputs, assigns a free confirmed market anchor, and builds 1..100 zero-fee v3 alternative parents sharing that funding set, returning the fund_policy_offer wallet request. Reserves nothing. 503 `offer_capacity_full` (retryable) when no anchor is free; 409 `open_offer_limit` at the per-address cap of open funding sets. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "requestBody": { "$ref": "#/components/requestBodies/PolicyOfferPreflight" }, "responses": { "200": { "$ref": "#/components/responses/PolicyOfferPreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-offers": { "post": { "operationId": "placePolicyOffer", "summary": "Place a collection offer", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "Verifies every bidder-signed parent against chain prevouts and the committed leaf, seals the parents at rest, and stores the funding set, all alternatives, and the anchor commitment atomically (all or none). An identical retry answers 200 with already_placed. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "requestBody": { "$ref": "#/components/requestBodies/PolicyOfferPlacement" }, "responses": { "200": { "description": "Successful placePolicyOffer response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WirePolicyOfferPlacementResult" } } } } } }, "201": { "description": "Successful placePolicyOffer response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WirePolicyOfferPlacementResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-offers/{id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "cancelPolicyOffer", "summary": "Cancel a collection offer", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "Soft cancel: forwards the bidder's BIP-322 cancel to the market signer, which refuses to sign this parent from then on, and retires the alternative. Only spending a funding input invalidates it on chain (see cancel-transaction). Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "requestBody": { "$ref": "#/components/requestBodies/PolicyOfferCancel" }, "responses": { "200": { "description": "Successful cancelPolicyOffer response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WirePolicyOfferCancellationResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-offers/{id}/cancel-transaction": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "post": { "operationId": "policyOfferHardCancelTransaction", "summary": "Release collection offer funds", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "Hard cancel: an unsigned self-send of every funding input back to the bidder, which kills every alternative of the funding set on chain. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable. Rate limited as an expensive write (20 per minute per session address, or per IP when anonymous; 120 per IP across sessions).", "requestBody": { "$ref": "#/components/requestBodies/PolicyOfferHardCancel" }, "responses": { "200": { "description": "Successful policyOfferHardCancelTransaction response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WirePolicyOfferHardCancelResult" } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/policy-offers": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listBidderPolicyOffers", "summary": "Your collection offers", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "The bidder's policy offers, newest first (opaque keyset cursor). Session owner only. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "responses": { "200": { "$ref": "#/components/responses/PolicyOfferList" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/assets/{asset}/policy-offers": { "parameters": [ { "$ref": "#/components/parameters/Asset" } ], "get": { "operationId": "listAssetPolicyOffers", "summary": "Collection offers on an asset", "tags": [ "policy-offers" ], "description": "Live policy offers this asset matches (asset scope plus collection/trait policies of its curated collections), best price first, each with an estimated seller net at the current fee rate. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "responses": { "200": { "$ref": "#/components/responses/PolicyOfferList" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/collections/{slug}/policy-offers": { "parameters": [ { "$ref": "#/components/parameters/Slug" } ], "get": { "operationId": "listCollectionPolicyOffers", "summary": "A collection’s collection offers", "tags": [ "policy-offers" ], "description": "A collection's live policy demand: collection/trait offers plus asset offers on its members, with estimated seller nets. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "responses": { "200": { "$ref": "#/components/responses/PolicyOfferList" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-accepts/preflight": { "post": { "operationId": "preflightPolicyAccept", "summary": "Quote a collection offer sale", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "For any attached, confirmed, one-unit asset UTXO the session owns (listed or merely prepared): checks eligibility and builds the v3 acceptance child (the seller pays the marketplace fee and the package network fee), returning the accept_policy_offer wallet request. A short-lived quote; reserves nothing. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "requestBody": { "$ref": "#/components/requestBodies/PolicyAcceptPreflight" }, "responses": { "201": { "$ref": "#/components/responses/PolicyAcceptPreflight" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-accepts": { "post": { "operationId": "submitPolicyAccept", "summary": "Sell into a collection offer", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "The seller-signed child: verified byte-for-byte against the quote, then atomically claims the funding set and the asset outpoint (first valid signature wins across checkout, exact offers, and accepts), is co-signed by the market signer, journaled with its parent, and submitted as a package. 202 when the journaled package is still being relayed by recovery. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "requestBody": { "$ref": "#/components/requestBodies/PolicyAcceptSubmit" }, "responses": { "200": { "$ref": "#/components/responses/PolicyAccept" }, "202": { "$ref": "#/components/responses/PolicyAccept" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/policy-accepts/{id}": { "parameters": [ { "$ref": "#/components/parameters/Id" } ], "get": { "operationId": "getPolicyAccept", "summary": "Collection offer sale status", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "Lifecycle of one acceptance (never its bytes). Seller session only. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "responses": { "200": { "$ref": "#/components/responses/PolicyAccept" }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/address/{address}/policy-accepts": { "parameters": [ { "$ref": "#/components/parameters/Address" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "get": { "operationId": "listSellerPolicyAccepts", "summary": "Your collection offer sales", "tags": [ "policy-offers" ], "security": [ { "session": [] } ], "description": "The seller's signed-or-later acceptances, newest first (opaque keyset cursor). Session owner only. Every policy-offer route answers 503 `service_unavailable` when collection-offer signing is unavailable.", "responses": { "200": { "description": "Successful listSellerPolicyAccepts response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WirePolicyAcceptResult" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "4XX": { "$ref": "#/components/responses/Error" }, "5XX": { "$ref": "#/components/responses/Error" } } } }, "/v1/artists/{key}/edit": { "post": { "operationId": "getArtistEditability", "summary": "Check current artist editing eligibility", "tags": [ "Artists" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-session-token", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistEditEnvelope" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Wallet session required" }, "403": { "description": "Wallet ineligible" }, "404": { "description": "Artist missing" }, "409": { "description": "Profile changed or URL reserved" }, "429": { "description": "Rate limited" }, "503": { "description": "Ownership unavailable" } }, "security": [ { "session": [] } ] } }, "/v1/artists/{key}/profile": { "post": { "operationId": "saveArtistProfile", "summary": "Save artist profile with fresh ownership and version checks", "tags": [ "Artists" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-session-token", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistDetailEnvelope" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Wallet session required" }, "403": { "description": "Wallet ineligible" }, "404": { "description": "Artist missing" }, "409": { "description": "Profile changed or URL reserved" }, "429": { "description": "Rate limited" }, "503": { "description": "Ownership unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistProfileInput" } } } }, "security": [ { "session": [] } ] } }, "/v1/analytics": { "get": { "operationId": "getMarketAnalytics", "summary": "Public marketplace analytics", "tags": [ "market" ], "security": [], "description": "Public snapshot, cached for 60 seconds. Current fillable public listings and total asking value; open public offers counted once per shared funding slot across interactive and policy offers. Private counters and specific-UTXO offers are excluded. Sales figures, daily UTC volume and the ten largest individual sales cover confirmed, non-dropped fills broadcast in the trailing 30 days. Buyers and sellers count unique addresses, not people. No operator or account-only information is included.", "responses": { "200": { "description": "Successful getMarketAnalytics response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/WireMarketAnalytics" } } } } } }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "session": { "type": "apiKey", "in": "header", "name": "x-session-token" } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "Slug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, "Address": { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/BitcoinAddress" } }, "Asset": { "name": "asset", "in": "path", "required": true, "description": "Canonical compact Counterparty asset ID, never a subasset longname.", "schema": { "$ref": "#/components/schemas/AssetId" } }, "AssetReadIdentity": { "name": "asset", "in": "path", "required": true, "description": "Canonical compact Counterparty asset ID or exact case-sensitive subasset longname.", "schema": { "type": "string", "minLength": 3, "maxLength": 250 } }, "CollectionFilter": { "name": "collection", "in": "query", "required": false, "description": "Optional collection scope. Mutually exclusive with the asset filter.", "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,99}$" } }, "AssetFilter": { "name": "asset", "in": "query", "required": false, "description": "Optional canonical compact Counterparty asset scope. Mutually exclusive with the collection filter.", "schema": { "$ref": "#/components/schemas/AssetId" } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque (created_at,id) continuation token returned as next_cursor.", "schema": { "type": "string" } } }, "responses": { "ArtistList": { "description": "ArtistList", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistListEnvelope" } } } }, "ArtistDetail": { "description": "ArtistDetail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistDetailEnvelope" } } } }, "ArtistAssetList": { "description": "ArtistAssetList", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtistAssetListEnvelope" } } } }, "PolicyOfferPreflight": { "description": "Unsigned zero-fee v3 alternative parents and the fund_policy_offer wallet request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyOfferPreflightEnvelope" } } } }, "PolicyOfferList": { "description": "Policy offers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyOfferListEnvelope" } } } }, "PolicyAcceptPreflight": { "description": "An unsigned v3 acceptance child and the accept_policy_offer wallet request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAcceptPreflightEnvelope" } } } }, "PolicyAccept": { "description": "Policy acceptance lifecycle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyAcceptEnvelope" } } } }, "FeeRates": { "description": "Current mempool fee tiers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeeRatesEnvelope" } } } }, "CollectionList": { "description": "Curated collection summaries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionListEnvelope" } } } }, "SearchResults": { "description": "Collections and assets matching the query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResultsEnvelope" } } } }, "CollectionDetail": { "description": "Collection identity and market summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDetailEnvelope" } } } }, "CollectionAssetList": { "description": "Paged collection asset market rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionAssetListEnvelope" } } } }, "CollectionOfferTargets": { "description": "Listed outpoints a collection offer policy would pre-authorize, with the count of assets the policy reaches at all", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionOfferTargetsEnvelope" } } } }, "CollectionFacets": { "description": "Collection-wide facet counts for the browse rail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionFacetsEnvelope" } } } }, "CollectionBook": { "description": "Bounded collection asks, policy demand, and fills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionBookEnvelope" } } } }, "CollectionHolders": { "description": "Collection ownership summary from the marketplace balance projection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionHoldersEnvelope" } } } }, "AssetDetail": { "description": "Asset facts and market summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDetailEnvelope" } } } }, "OfferSummaries": { "description": "Best individual and collection/trait offers per asset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferSummariesEnvelope" } } } }, "AssetBook": { "description": "Ask/bid depth, fillable rows, and recent fills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBookEnvelope" } } } }, "ListingList": { "description": "Newest public listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingListEnvelope" } } } }, "SellerListingList": { "description": "Seller listing portfolio", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerListingListEnvelope" } } } }, "EndedListingList": { "description": "Recently ended seller listings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndedListingListEnvelope" } } } }, "FillList": { "description": "Global fill activity, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillListEnvelope" } } } }, "MarketEventList": { "description": "One page of the public market event feed, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "additionalProperties": false, "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/MarketEvent" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "AuthChallenge": { "description": "Stateless BIP-322 challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthChallengeEnvelope" } } } }, "MarketplaceSession": { "description": "Address-bound marketplace session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceSessionEnvelope" } } } }, "ListingPreflight": { "description": "Durable listing operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingPreflightEnvelope" } } } }, "TransactionRecovery": { "description": "No-store Bitcoin recovery evidence; unknown is never unspent or cancelled", "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "additionalProperties": false, "properties": { "result": { "$ref": "#/components/schemas/TransactionRecovery" } } } } } }, "TransactionRelay": { "description": "The txid the network echoed for the relayed bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRelayEnvelope" } } } }, "AttachTemplate": { "description": "One verified attach template, never stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachTemplateEnvelope" } } } }, "AttachSpeedUp": { "description": "One unsigned speed-up child, never stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachSpeedUpEnvelope" } } } }, "OwnerEventList": { "description": "One page of the owner event feed, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "additionalProperties": false, "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/OwnerEvent" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "ListingRepricePreflight": { "description": "Stateless replacement listing authorization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingRepricePreflightEnvelope" } } } }, "OfferFundingPreflight": { "description": "Verified exact-value offer funding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferFundingPreflightEnvelope" } } } }, "FillQuote": { "description": "Non-reserving checkout quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillQuoteEnvelope" } } } }, "Error": { "description": "Stable machine-readable failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "OfferFundingTemplate": { "description": "An unsigned offer funding template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferFundingTemplateEnvelope" } } } } }, "requestBodies": { "OfferCancellationReview": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferCancellationReview" } } } }, "PolicyOfferPreflight": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bidder_public_key", "alternatives" ], "properties": { "bidder_public_key": { "$ref": "#/components/schemas/Hex", "description": "P2TR: the 32-byte x-only internal key. P2WPKH: the 33-byte compressed key. Must own the session address." }, "delivery_address": { "$ref": "#/components/schemas/DeliveryAddress", "description": "Detach destination (any family); defaults to the session address." }, "alternatives": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "price_sats", "expires_at", "policy" ], "properties": { "price_sats": { "$ref": "#/components/schemas/Sats" }, "expires_at": { "type": "integer", "description": "Unix seconds in [now + 600, now + 90 days]." }, "policy": { "$ref": "#/components/schemas/CanonicalPolicy" } }, "additionalProperties": false } }, "funding": { "type": "array", "maxItems": 8, "items": { "$ref": "#/components/schemas/Outpoint" }, "description": "Explicit funding inputs; otherwise confirmed asset-free coins are selected." }, "exclude": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/Outpoint" } } }, "additionalProperties": false } } } }, "PolicyOfferPlacement": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "bidder_public_key", "alternatives" ], "properties": { "bidder_public_key": { "$ref": "#/components/schemas/Hex" }, "alternatives": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "psbt_hex", "leaf_hex", "policy" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "leaf_hex": { "$ref": "#/components/schemas/Hex" }, "policy": { "$ref": "#/components/schemas/CanonicalPolicy" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "PolicyOfferCancel": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "signature" ], "properties": { "address": { "$ref": "#/components/schemas/BitcoinAddress" }, "signature": { "type": "string", "description": "BIP-322 simple signature (base64) over `digirare policy-offer cancel ` by an address K_b owns." } }, "additionalProperties": false } } } }, "PolicyOfferHardCancel": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "PolicyAcceptPreflight": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parent_txid", "asset_txid", "asset_vout" ], "properties": { "parent_txid": { "$ref": "#/components/schemas/Txid" }, "asset_txid": { "$ref": "#/components/schemas/Txid" }, "asset_vout": { "type": "integer", "minimum": 0 }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "seller_min_net_sats": { "type": "integer", "minimum": 0 }, "seller_tap_internal_key": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false } } } }, "PolicyAcceptSubmit": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accept_id", "psbt_hex" ], "properties": { "accept_id": { "type": "string" }, "psbt_hex": { "$ref": "#/components/schemas/Hex", "description": "The quoted child with the seller's input-1 signature (DEFAULT/ALL)." } }, "additionalProperties": false } } } }, "SignedPsbt": { "required": true, "description": "Hex PSBT with the wallet's owned inputs signed. Signature fields and already-finalized native P2TR/P2WPKH witnesses are both accepted and independently verified.", "content": { "application/json": { "schema": { "type": "object", "required": [ "psbt_hex" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false } } } }, "SignedExactAccept": { "required": true, "description": "The seller-signed exact-offer parent PSBT (the unsigned template with the seller signature on input 1; the market merges the stored buyer signature) plus the seller-signed CPFP PSBT when the current fee_adjustment state requires it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "psbt_hex" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "cpfp_psbt_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false } } } }, "FinalListing": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "psbt_hex" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "expires_at": { "type": [ "integer", "null" ] } }, "additionalProperties": false } } } }, "RelayTransaction": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "raw_tx_hex" ], "properties": { "raw_tx_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false } } } }, "QuoteAttachSpeedUp": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "owner", "txid" ], "properties": { "owner": { "$ref": "#/components/schemas/BitcoinAddress", "description": "The session address whose change pays for the speed-up." }, "txid": { "$ref": "#/components/schemas/Txid", "description": "The unconfirmed attach to speed up. For a chain of attaches, the newest one: its change is the unspent one, and its package carries every ancestor." }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "ComposeAttachTemplate": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "utxo_owner", "asset" ], "properties": { "utxo_owner": { "$ref": "#/components/schemas/BitcoinAddress" }, "asset_source": { "$ref": "#/components/schemas/AssetSourceAddress" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "exclude": { "type": "array", "maxItems": 200, "description": "Coins server selection must skip: inputs the caller already committed in earlier legs that chain data cannot yet show as spent.", "items": { "$ref": "#/components/schemas/Outpoint" } }, "in_flight": { "type": "array", "maxItems": 800, "description": "The caller's own attaches from this source that may still be moving units, as asset and raw units each one moves (the XCP protocol fee under XCP). A signed attach names its asset_utxo and stays declared until it is FINALITY_DEPTH deep: the server skips entries whose asset UTXO its balance projection currently shows attached (already out of the detached balance) and counts the rest, so an attach a reorg un-parsed counts again. Entries without asset_utxo always count. Only ever subtracted from the held balance, so the server refuses composing units those attaches already use.", "items": { "type": "object", "required": [ "asset", "quantity_raw" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity_raw": { "type": "string", "pattern": "^[0-9]{1,30}$" }, "asset_utxo": { "$ref": "#/components/schemas/Outpoint" } }, "additionalProperties": false } }, "funding": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Exact inputs this attach may spend. Supply script_pub_key_hex on every input to spend an unconfirmed parent's change; omit it on all of them for confirmed coins.", "items": { "type": "object", "required": [ "txid", "vout", "value_sats" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 }, "value_sats": { "$ref": "#/components/schemas/Sats" }, "script_pub_key_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "CreateListingPreflight": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idempotency_key", "seller", "asset" ], "properties": { "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Client-generated key reused for retries of the same create instruction." }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "asset_source": { "$ref": "#/components/schemas/AssetSourceAddress" }, "asset_utxo": { "type": "object", "description": "Prepared-only listing of this exact output. It must belong to seller; unavailable inventory is refused, never replaced or attached again.", "required": [ "txid", "vout" ], "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "vout": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "additionalProperties": false }, "asset": { "$ref": "#/components/schemas/AssetId" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "ListingBatch": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ListingBatchRepricePreflight" }, { "$ref": "#/components/schemas/ListingBatchReprice" }, { "$ref": "#/components/schemas/ListingBatchDelist" } ] } } } }, "RepricePreflight": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "price_sats" ], "properties": { "price_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false } } } }, "SignedAttachAndListing": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "attach_psbt_hex", "listing_psbt_hex" ], "properties": { "attach_psbt_hex": { "$ref": "#/components/schemas/Hex" }, "listing_psbt_hex": { "$ref": "#/components/schemas/Hex" }, "expires_at": { "type": [ "integer", "null" ] } }, "additionalProperties": false } } } }, "FillRequest": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CartFillRequest" }, { "$ref": "#/components/schemas/CounterFillRequest" } ] } } } }, "CompleteFill": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fill_id", "psbt_hex" ], "properties": { "fill_id": { "type": "string" }, "psbt_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false } } } }, "PlaceOffers": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOffers" } } } }, "OfferFundingPreflight": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txid", "vout" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } } } }, "ValidateOfferAcceptanceSelection": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferAcceptanceSelection" } } } }, "AcceptOffer": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "utxo_txid", "utxo_vout" ], "properties": { "utxo_txid": { "$ref": "#/components/schemas/Txid" }, "utxo_vout": { "type": "integer", "minimum": 0 }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "ExactAuthorizationBatch": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targets" ], "properties": { "targets": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "required": [ "utxo_txid", "utxo_vout" ], "properties": { "utxo_txid": { "$ref": "#/components/schemas/Txid" }, "utxo_vout": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "FundedAuthorizationTemplates": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "funding_psbt_hex", "slot_vout", "targets", "assets", "expires_at" ], "properties": { "funding_psbt_hex": { "type": "string", "pattern": "^(?:[0-9a-fA-F]{2})+$", "description": "The unsigned `funding.psbt_hex` from `POST /v1/offer-funding-templates`." }, "slot_vout": { "type": "integer", "minimum": 0 }, "targets": { "type": "array", "minItems": 1, "maxItems": 7, "items": { "type": "object", "required": [ "utxo_txid", "utxo_vout" ], "properties": { "utxo_txid": { "$ref": "#/components/schemas/Txid" }, "utxo_vout": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "assets": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "description": "The placement's asset-scope targets, as `POST /v1/funded-offers` will receive them." }, "expires_at": { "type": "integer" }, "receive_address": { "type": "string" }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ] }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "AddressOnly": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address" ], "properties": { "address": { "$ref": "#/components/schemas/BitcoinAddress" } }, "additionalProperties": false } } } }, "ConnectionProof": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "message", "signature" ], "properties": { "address": { "$ref": "#/components/schemas/BitcoinAddress" }, "message": { "type": "string" }, "signature": { "type": "string" }, "verification": { "$ref": "#/components/schemas/MessageSignatureVerification" } }, "additionalProperties": false } } } }, "ChallengeProof": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "issued_at", "signature" ], "properties": { "address": { "$ref": "#/components/schemas/BitcoinAddress" }, "issued_at": { "type": "integer" }, "signature": { "type": "string" }, "verification": { "$ref": "#/components/schemas/MessageSignatureVerification" } }, "additionalProperties": false } } } }, "OfferFundingTemplate": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "price_sats" ], "properties": { "price_sats": { "$ref": "#/components/schemas/Sats", "description": "The offer per edition. An attached-delivery bid output also includes the 330 sat buyer-owned asset UTXO." }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ], "default": "detached" }, "slot_count": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1, "description": "How many editions the offer can fill; one bid output each." }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "tap_internal_key": { "$ref": "#/components/schemas/Hex", "description": "The bidder's 32-byte x-only internal key; required for a P2TR bidder so the wallet can key-path sign." }, "exclude": { "type": "array", "maxItems": 200, "description": "Outpoints the caller already spent in earlier legs of this run; never chosen as funding.", "items": { "$ref": "#/components/schemas/Outpoint" } } }, "additionalProperties": false } } } }, "OfferSlotRelease": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slots", "bidder_public_key" ], "properties": { "slots": { "type": "array", "minItems": 1, "maxItems": 20, "description": "The owner's bid slots to spend, in input order.", "items": { "$ref": "#/components/schemas/Outpoint" } }, "bidder_public_key": { "$ref": "#/components/schemas/Hex", "description": "P2TR: the 32-byte x-only internal key; P2WPKH: the 33-byte compressed key. Must own the session address's script." }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false } } } }, "FundedOffers": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "funding_tx_hex", "bids", "targets", "expires_at" ], "properties": { "funding_tx_hex": { "$ref": "#/components/schemas/Hex", "description": "The fully signed, finalized funding transaction. Its outputs are the only authority for each bid's value." }, "bids": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Which outputs of the funding transaction are bid slots; `txid`, when given, must be the transaction's own.", "items": { "$ref": "#/components/schemas/Outpoint" } }, "targets": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/OfferTarget" } }, "expires_at": { "type": "integer" }, "receive_address": { "$ref": "#/components/schemas/DeliveryAddress" }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ], "default": "detached" } }, "additionalProperties": false } } } } }, "schemas": { "OfferCancellationReview": { "type": "object", "required": [ "offer_ids" ], "properties": { "offer_ids": { "type": "array", "minItems": 1, "maxItems": 99, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 128 } } } }, "ArtistSummary": { "type": "object", "required": [ "name", "key", "assets", "collections", "id", "preview_assets" ], "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "assets": { "type": "integer", "minimum": 0 }, "collections": { "type": "integer", "minimum": 0 }, "id": { "type": "string" }, "preview_assets": { "type": "array", "description": "Up to eight distinct artworks sampled across collections, using effective artist attribution.", "maxItems": 8, "items": { "$ref": "#/components/schemas/ArtistPreviewAsset" } } }, "additionalProperties": false }, "ArtistDetail": { "type": "object", "required": [ "name", "key", "assets", "listed", "floor_sats", "collections", "id", "bio", "website", "x_url", "version" ], "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "assets": { "type": "integer", "minimum": 0 }, "listed": { "type": "integer", "minimum": 0 }, "floor_sats": { "type": [ "integer", "null" ], "minimum": 0 }, "collections": { "type": "array", "items": { "type": "object", "required": [ "slug", "name", "assets" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "assets": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "id": { "type": "string" }, "bio": { "type": "string" }, "website": { "type": "string" }, "x_url": { "type": "string" }, "version": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ArtistAsset": { "type": "object", "required": [ "asset", "asset_longname", "issued_year", "supply_units", "media_kind", "protocol_subtype", "collection", "collection_name", "art_frame", "floor_sats", "listed" ], "properties": { "asset": { "type": "string" }, "asset_longname": { "type": [ "string", "null" ] }, "issued_year": { "type": [ "integer", "null" ] }, "supply_units": { "type": "number" }, "media_kind": { "type": [ "string", "null" ], "enum": [ "image", "animation", "video", "html", "svg", null ] }, "protocol_subtype": { "type": [ "string", "null" ] }, "collection": { "type": "string" }, "collection_name": { "type": "string" }, "art_frame": { "type": "string", "enum": [ "card", "square", "landscape" ] }, "floor_sats": { "type": [ "integer", "null" ], "minimum": 0 }, "listed": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "ArtistListEnvelope": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ArtistSummary" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ArtistAssetListEnvelope": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ArtistAsset" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ArtistDetailEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/ArtistDetail" } }, "additionalProperties": false }, "CanonicalPolicy": { "type": "object", "description": "funded_policy_offer_v1 canonical policy (spec 4.4). Exactly these keys, absent traits null; SHA256 of its canonical JSON is the leaf's policy hash.", "required": [ "scope", "asset", "collection", "max_supply_units", "min_supply_units", "issued_year", "series", "artist" ], "properties": { "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "asset": { "oneOf": [ { "$ref": "#/components/schemas/AssetId" }, { "type": "null" } ] }, "collection": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120 }, "max_supply_units": { "type": [ "integer", "null" ], "minimum": 0 }, "min_supply_units": { "type": [ "integer", "null" ], "minimum": 0 }, "issued_year": { "type": [ "integer", "null" ], "minimum": 0 }, "series": { "type": [ "integer", "null" ], "minimum": 0 }, "artist": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "PolicyOfferEstimate": { "type": [ "object", "null" ], "description": "Estimated seller take at the current fee rate (P2TR seller and fee outputs, 330-sat asset UTXO). A quote, not a promise.", "properties": { "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "child_vsize": { "type": "integer" }, "package_vsize": { "type": "integer" }, "network_fee_sats": { "$ref": "#/components/schemas/Sats" }, "platform_fee_sats": { "$ref": "#/components/schemas/Sats" }, "seller_net_sats": { "type": "integer" }, "acceptable": { "type": "boolean" } } }, "PolicyOfferSummary": { "type": "object", "required": [ "protocol_version", "parent_txid", "funding_slot_id", "bidder", "kind", "price_sats", "offer_value_sats", "expires_at", "parent_vsize", "scope" ], "properties": { "protocol_version": { "const": "funded_policy_offer_v1" }, "parent_txid": { "$ref": "#/components/schemas/Txid" }, "funding_slot_id": { "type": "string", "description": ":; alternatives sharing it are mutually exclusive." }, "bidder": { "$ref": "#/components/schemas/BitcoinAddress" }, "kind": { "type": "string", "enum": [ "asset", "collection", "trait" ] }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "offer_value_sats": { "$ref": "#/components/schemas/Sats" }, "expires_at": { "type": "integer" }, "parent_vsize": { "type": "integer", "maximum": 1000 }, "parent_fee_sats": { "type": "integer", "minimum": 0, "maximum": 329 }, "created_at": { "type": "integer" }, "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "asset": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "max_supply_units": { "type": [ "integer", "null" ] }, "min_supply_units": { "type": [ "integer", "null" ] }, "issued_year": { "type": [ "integer", "null" ] }, "series": { "type": [ "integer", "null" ] }, "artist": { "type": [ "string", "null" ] }, "estimate": { "$ref": "#/components/schemas/PolicyOfferEstimate" }, "status": { "type": "string", "enum": [ "active", "expired", "pending", "filled", "superseded", "cancelled", "invalid" ], "description": "Bidder history only." }, "market_key_exposure_sats": { "type": "integer", "description": "Bidder history only: the market key can execute up to this while the funding inputs and anchor are unspent." } }, "additionalProperties": true }, "PolicyOfferListEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyOfferSummary" } }, "result_count": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ] } } }, "PolicyOfferPreflight": { "type": "object", "required": [ "protocol_version", "operation_id", "bidder", "internal_key", "market_key", "funding_slot_id", "funding_inputs", "anchor", "delivery", "alternatives", "wallet_request", "network_fee_sats", "reserves_funding" ], "properties": { "protocol_version": { "const": "funded_policy_offer_v1" }, "operation_id": { "type": "string" }, "bidder": { "$ref": "#/components/schemas/BitcoinAddress" }, "internal_key": { "$ref": "#/components/schemas/Hex" }, "market_key": { "$ref": "#/components/schemas/Hex" }, "funding_slot_id": { "type": "string" }, "funding_inputs": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "object", "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer" }, "value_sats": { "$ref": "#/components/schemas/Sats" } } } }, "anchor": { "type": "object", "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer" }, "value_sats": { "const": 330 } } }, "delivery": { "type": "object", "properties": { "mode": { "const": "detached" }, "address": { "$ref": "#/components/schemas/DeliveryAddress" } } }, "alternatives": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "parent_txid": { "$ref": "#/components/schemas/Txid" }, "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "leaf_hex": { "$ref": "#/components/schemas/Hex" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "offer_value_sats": { "$ref": "#/components/schemas/Sats" }, "expires_at": { "type": "integer" }, "policy": { "$ref": "#/components/schemas/CanonicalPolicy" }, "policy_hash": { "$ref": "#/components/schemas/Hex" }, "kind": { "type": "string" }, "parent_vsize": { "type": "integer" }, "parent_fee_sats": { "type": "integer" }, "change_sats": { "type": "integer" }, "detach_script_hex": { "$ref": "#/components/schemas/Hex" } } } }, "signing": { "type": "object" }, "intent": { "type": "object", "description": "fund_policy_offer wallet intent claim (policy-offer-wallet.ts)." }, "wallet_request": { "type": "object", "description": "xcp_signPsbts request: one PSBT per alternative, funding inputs only." }, "network_fee_sats": { "const": 0 }, "market_key_exposure_sats": { "$ref": "#/components/schemas/Sats" }, "reserves_funding": { "const": false } }, "additionalProperties": false }, "PolicyOfferPreflightEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/PolicyOfferPreflight" } } }, "PolicyAcceptPreflight": { "type": "object", "required": [ "protocol_version", "accept_id", "parent_txid", "seller", "asset", "asset_outpoint", "psbt_hex", "expected_txid", "price_sats", "platform_fee_sats", "network_fee_sats", "seller_proceeds_sats", "parent_vsize", "child_vsize", "fee_rate", "wallet_request", "expires_at", "reserves_inventory" ], "properties": { "protocol_version": { "const": "funded_policy_offer_v1" }, "accept_id": { "type": "string" }, "parent_txid": { "$ref": "#/components/schemas/Txid" }, "funding_slot_id": { "type": "string" }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity_raw": { "$ref": "#/components/schemas/RawQuantity" }, "asset_outpoint": { "$ref": "#/components/schemas/Outpoint" }, "utxo_value_sats": { "$ref": "#/components/schemas/Sats" }, "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "expected_txid": { "$ref": "#/components/schemas/Txid" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "offer_value_sats": { "$ref": "#/components/schemas/Sats" }, "platform_fee_sats": { "$ref": "#/components/schemas/Sats" }, "network_fee_sats": { "$ref": "#/components/schemas/Sats" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/Sats" }, "parent_vsize": { "type": "integer" }, "child_vsize": { "type": "integer" }, "package_vsize": { "type": "integer" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "delivery": { "type": "object" }, "signing": { "type": "object" }, "intent": { "type": "object", "description": "accept_policy_offer wallet intent claim." }, "wallet_request": { "type": "object" }, "expires_at": { "type": "integer" }, "reserves_inventory": { "const": false } }, "additionalProperties": false }, "PolicyAcceptPreflightEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/PolicyAcceptPreflight" } } }, "PolicyAccept": { "type": "object", "required": [ "protocol_version", "accept_id", "status", "parent_txid", "child_txid", "asset", "seller", "price_sats", "platform_fee_sats", "network_fee_sats", "seller_proceeds_sats" ], "properties": { "protocol_version": { "const": "funded_policy_offer_v1" }, "accept_id": { "type": "string" }, "status": { "type": "string", "enum": [ "quoted", "signed", "journaled", "broadcast", "confirmed", "conflicted", "failed" ] }, "parent_txid": { "$ref": "#/components/schemas/Txid" }, "child_txid": { "$ref": "#/components/schemas/Txid" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "asset_outpoint": { "$ref": "#/components/schemas/Outpoint" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "platform_fee_sats": { "$ref": "#/components/schemas/Sats" }, "network_fee_sats": { "$ref": "#/components/schemas/Sats" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/Sats" }, "refusal_code": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "settlement": { "type": [ "object", "null" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "already_completed": { "type": "boolean" }, "id": { "type": "string" } }, "additionalProperties": false }, "PolicyAcceptEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/PolicyAccept" } } }, "FeeRatesEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/FeeRates" } }, "additionalProperties": false }, "CollectionListEnvelope": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSummary" } }, "result_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "CollectionDetailEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/CollectionDetail" } }, "additionalProperties": false }, "CollectionAssetListEnvelope": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/AssetSummary" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CollectionBookEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/CollectionBook" } }, "additionalProperties": false }, "CollectionSupplyBucket": { "type": "string", "description": "Fixed supply buckets in whole units: one = exactly 1, small = 2 to 100, mid = 101 to 500, large = over 500.", "enum": [ "one", "small", "mid", "large" ] }, "CollectionFacets": { "type": "object", "required": [ "series", "supply", "years", "artists", "traits" ], "properties": { "years": { "type": "array", "items": { "type": "object", "required": [ "year", "count" ], "properties": { "year": { "type": "integer", "minimum": 0 }, "count": { "type": "integer", "minimum": 1 } } } }, "artists": { "type": "array", "items": { "type": "object", "required": [ "artist", "count" ], "properties": { "artist": { "type": "string" }, "count": { "type": "integer", "minimum": 1 } } } }, "series": { "type": "array", "items": { "type": "object", "required": [ "series", "count" ], "properties": { "series": { "type": "integer", "minimum": 0 }, "count": { "type": "integer", "minimum": 1 } } } }, "supply": { "type": "array", "items": { "type": "object", "required": [ "bucket", "count" ], "properties": { "bucket": { "$ref": "#/components/schemas/CollectionSupplyBucket" }, "count": { "type": "integer", "minimum": 1 } } } }, "traits": { "type": "array", "items": { "type": "object", "required": [ "name", "values" ], "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "required": [ "value", "count" ], "properties": { "value": { "type": "string" }, "count": { "type": "integer", "minimum": 1 } } } } } } } } }, "CollectionOfferTargetsEnvelope": { "type": "object", "required": [ "result", "result_count", "matching_assets" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListing" } }, "result_count": { "type": "integer", "minimum": 0 }, "matching_assets": { "type": "integer", "minimum": 0, "description": "Assets in the collection the policy reaches, listed or not" } } }, "CollectionFacetsEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/CollectionFacets" } } }, "CollectionHoldersEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/CollectionHolders" } }, "additionalProperties": false }, "AssetDetailEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/AssetDetail" } }, "additionalProperties": false }, "OfferSummariesEnvelope": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/AssetOfferSummary" } }, "result_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "AssetOfferSummary": { "type": "object", "required": [ "asset", "best_offer", "individual_offer", "collection_offer" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetId" }, "best_offer": { "$ref": "#/components/schemas/CollectionBookOffer" }, "individual_offer": { "oneOf": [ { "$ref": "#/components/schemas/CollectionBookOffer" }, { "type": "null" } ] }, "collection_offer": { "oneOf": [ { "$ref": "#/components/schemas/CollectionBookOffer" }, { "type": "null" } ] } }, "additionalProperties": false }, "AssetBookEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/AssetBook" } }, "additionalProperties": false }, "ListingListEnvelope": { "type": "object", "required": [ "result", "result_count" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListing" } }, "result_count": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "SellerListingListEnvelope": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/SellerListing" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "EndedListingListEnvelope": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/EndedListing" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "FillListEnvelope": { "type": "object", "required": [ "result", "result_count", "next_cursor" ], "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/FillActivity" } }, "result_count": { "type": "integer", "minimum": 0 }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "AuthChallengeEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/AuthChallenge" } }, "additionalProperties": false }, "MarketplaceSessionEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/MarketplaceSession" } }, "additionalProperties": false }, "FeeRates": { "type": "object", "required": [ "fastest", "half_hour", "hour", "economy", "minimum", "recommended" ], "properties": { "fastest": { "type": "number" }, "half_hour": { "type": "number" }, "hour": { "type": "number" }, "economy": { "type": "number" }, "minimum": { "type": "number" }, "recommended": { "type": "number" } }, "additionalProperties": false }, "CollectionSummary": { "type": "object", "required": [ "slug", "name", "kind", "art_frame", "blurb", "listable", "sort_rank", "assets", "listed", "floor_sats", "volume_24h_sats", "sales_24h", "volume_7d_sats", "sales_7d", "volume_30d_sats", "sales_30d", "volume_all_sats", "sales_all", "first_issued_year", "last_issued_year", "founded_year", "website_url", "x_url" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "canonical", "curated" ] }, "art_frame": { "type": "string", "enum": [ "card", "square", "landscape" ] }, "blurb": { "type": [ "string", "null" ] }, "listable": { "type": "integer", "enum": [ 0, 1 ] }, "sort_rank": { "type": "integer" }, "assets": { "type": "integer", "minimum": 0 }, "listed": { "type": "integer", "minimum": 0 }, "floor_sats": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] }, "volume_24h_sats": { "type": "integer", "minimum": 0, "description": "Gross satoshis filled; zero when nothing traded" }, "sales_24h": { "type": "integer", "minimum": 0, "description": "Filled items; a cart of three listings is three sales" }, "volume_7d_sats": { "type": "integer", "minimum": 0, "description": "Gross satoshis filled; zero when nothing traded" }, "sales_7d": { "type": "integer", "minimum": 0, "description": "Filled items; a cart of three listings is three sales" }, "volume_30d_sats": { "type": "integer", "minimum": 0, "description": "Gross satoshis filled; zero when nothing traded" }, "sales_30d": { "type": "integer", "minimum": 0, "description": "Filled items; a cart of three listings is three sales" }, "volume_all_sats": { "type": "integer", "minimum": 0, "description": "Gross satoshis filled; zero when nothing traded" }, "sales_all": { "type": "integer", "minimum": 0, "description": "Filled items; a cart of three listings is three sales" }, "first_issued_year": { "type": [ "integer", "null" ], "description": "Issue year of the earliest member asset; null until one is known" }, "last_issued_year": { "type": [ "integer", "null" ], "description": "Issue year of the latest member asset; null until one is known" }, "founded_year": { "type": [ "integer", "null" ], "description": "Curated founding year from the registry; the era label starts here when present" }, "website_url": { "type": [ "string", "null" ], "description": "Official site from the registry's links, https only" }, "x_url": { "type": [ "string", "null" ], "description": "Official X account from the registry's links, https only" } } }, "AssetSummary": { "type": "object", "required": [ "asset", "asset_longname", "divisible", "supply_raw", "supply_units", "issued_year", "issued_block", "artist", "series", "card", "is_primary", "attributes_json", "protocol_ordinal", "protocol_subtype", "media_kind", "locked", "floor_sats", "listed", "best_asset_offer", "best_collection_offer", "best_offer_sats" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetId" }, "asset_longname": { "type": [ "string", "null" ] }, "divisible": { "type": "integer", "enum": [ 0, 1 ] }, "supply_raw": { "$ref": "#/components/schemas/RawQuantity" }, "supply_units": { "type": "integer", "minimum": 0 }, "issued_year": { "type": [ "integer", "null" ] }, "issued_block": { "type": [ "integer", "null" ] }, "artist": { "type": [ "string", "null" ] }, "series": { "type": [ "integer", "null" ] }, "card": { "type": [ "integer", "null" ] }, "is_primary": { "type": "integer", "enum": [ 0, 1 ] }, "attributes_json": { "type": [ "string", "null" ] }, "protocol_ordinal": { "type": [ "integer", "null" ], "minimum": 0 }, "protocol_subtype": { "type": [ "string", "null" ] }, "media_kind": { "type": [ "string", "null" ], "enum": [ "image", "animation", "video", "html", "svg", null ] }, "locked": { "type": "integer", "enum": [ 0, 1 ] }, "floor_sats": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] }, "listed": { "type": "integer", "minimum": 0 }, "best_asset_offer": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] }, "best_collection_offer": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] }, "best_offer_sats": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] } } }, "CollectionDetail": { "allOf": [ { "$ref": "#/components/schemas/CollectionSummary" }, { "type": "object", "required": [ "offers", "holders" ], "properties": { "offers": { "type": "integer", "minimum": 0, "description": "Distinct live funding slots (bid UTXOs and standing-offer fundings) behind the collection's collection, trait, and member-asset offers" }, "holders": { "type": [ "integer", "null" ], "minimum": 0, "description": "Distinct addresses holding a member asset, from the maintained holder projection; null until the balance index has bootstrapped" } } } ] }, "CollectionHolder": { "type": "object", "required": [ "address", "edition_units", "percent_collected", "distinct_assets", "assets" ], "properties": { "address": { "$ref": "#/components/schemas/BitcoinAddress" }, "edition_units": { "type": "number", "minimum": 0, "description": "Whole Counterparty units across this holder's collection balances" }, "percent_collected": { "type": "number", "minimum": 0, "maximum": 100, "description": "Share of distinct curated collection assets held" }, "distinct_assets": { "type": "integer", "minimum": 1 }, "assets": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/AssetId" } } }, "additionalProperties": false }, "CollectionHolders": { "type": "object", "required": [ "holders", "holder_count", "total_edition_units", "collection_assets", "indexed_assets", "as_of_event_index" ], "properties": { "holders": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/CollectionHolder" } }, "holder_count": { "type": "integer", "minimum": 0 }, "total_edition_units": { "type": "number", "minimum": 0 }, "collection_assets": { "type": "integer", "minimum": 0 }, "indexed_assets": { "type": "integer", "minimum": 0 }, "as_of_event_index": { "type": [ "integer", "null" ], "minimum": 0 } }, "additionalProperties": false }, "AssetDetail": { "allOf": [ { "$ref": "#/components/schemas/AssetSummary" }, { "type": "object", "required": [ "collection", "collection_name", "art_frame", "burned_raw", "media_kind", "art_width", "art_height", "art_bytes", "listable" ], "properties": { "art_width": { "type": [ "integer", "null" ], "minimum": 1 }, "art_height": { "type": [ "integer", "null" ], "minimum": 1 }, "art_bytes": { "type": [ "integer", "null" ], "minimum": 1 }, "collection": { "type": "string" }, "collection_name": { "type": "string" }, "art_frame": { "type": "string", "enum": [ "card", "square", "landscape" ] }, "media_kind": { "type": [ "string", "null" ], "enum": [ "image", "animation", "video", "html", "svg", null ], "description": "What the stored art is; null until classified." }, "burned_raw": { "oneOf": [ { "$ref": "#/components/schemas/RawQuantity" }, { "type": "null" } ], "description": "Raw quantity held by verified burn addresses; null until the asset's balances are projected." }, "listable": { "type": "integer", "enum": [ 0, 1 ] }, "artist_profile": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "id", "name", "key" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key": { "type": "string" } } } ] } } } ] }, "SearchAsset": { "type": "object", "required": [ "asset", "asset_longname", "collection", "collection_name", "supply_units", "issued_year", "listed", "floor_sats" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetId" }, "asset_longname": { "type": [ "string", "null" ] }, "collection": { "type": "string" }, "collection_name": { "type": "string" }, "supply_units": { "type": "integer" }, "issued_year": { "type": [ "integer", "null" ] }, "listed": { "type": "integer" }, "floor_sats": { "type": [ "integer", "null" ] } } }, "SearchResults": { "type": "object", "required": [ "collections", "assets" ], "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSummary" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/SearchAsset" } } } }, "SearchResultsEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/SearchResults" } } }, "BookLevel": { "type": "object", "required": [ "price_sats", "depth" ], "properties": { "price_sats": { "$ref": "#/components/schemas/Sats" }, "depth": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "PublicListing": { "type": "object", "required": [ "id", "asset", "seller", "utxo_txid", "utxo_vout", "quantity_raw", "price_sats", "created_at" ], "properties": { "id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "asset_longname": { "type": [ "string", "null" ] }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "utxo_txid": { "$ref": "#/components/schemas/Txid" }, "utxo_vout": { "type": "integer", "minimum": 0 }, "quantity_raw": { "$ref": "#/components/schemas/RawQuantity" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "created_at": { "type": "integer" }, "protocol_subtype": { "type": [ "string", "null" ] }, "media_kind": { "type": [ "string", "null" ], "enum": [ "image", "animation", "video", "html", "svg", null ] } } }, "SellerListing": { "allOf": [ { "$ref": "#/components/schemas/PublicListing" }, { "type": "object", "required": [ "status", "expires_at", "private_to" ], "properties": { "collection": { "type": [ "string", "null" ], "description": "The asset's primary listable collection (public storefront read only)." }, "status": { "type": "string", "enum": [ "active", "pending" ] }, "expires_at": { "type": [ "integer", "null" ] }, "private_to": { "oneOf": [ { "$ref": "#/components/schemas/BitcoinAddress" }, { "type": "null" } ] } } } ] }, "EndedListing": { "type": "object", "required": [ "id", "asset", "seller", "utxo_txid", "utxo_vout", "price_sats", "private_to", "counter_of", "created_at", "ended_at", "reason", "sale", "spent_txid" ], "properties": { "id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "utxo_txid": { "$ref": "#/components/schemas/Txid" }, "utxo_vout": { "type": "integer", "minimum": 0 }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "private_to": { "oneOf": [ { "$ref": "#/components/schemas/BitcoinAddress" }, { "type": "null" } ] }, "counter_of": { "type": [ "string", "null" ] }, "created_at": { "type": "integer" }, "ended_at": { "type": "integer", "description": "When the listing left the book (its last state change)." }, "reason": { "type": "string", "enum": [ "sold", "sold_via_offer", "sold_other_listing", "delisted", "expired", "counter_offer_ended", "moved", "reorg", "sale_dropped", "withdrawn" ], "description": "sold: filled by a DIGIRARE buyer. sold_via_offer: the unit sold through an accepted offer. sold_other_listing: a buyer took another listing of the same unit (its public listing or a private counter). delisted: cancelled by the seller. expired: its expiry passed. counter_offer_ended: a private counter retired because the offer it answered ended. moved: the asset UTXO was spent by a transaction no DIGIRARE fill or settlement names. reorg: a Bitcoin reorg undid the attach or the UTXO. sale_dropped: a DIGIRARE sale was broadcast but never confirmed. withdrawn: taken off the book because the unit stopped verifying, with no finer cause stored." }, "sale": { "oneOf": [ { "$ref": "#/components/schemas/EndedListingSale" }, { "type": "null" } ] }, "spent_txid": { "oneOf": [ { "$ref": "#/components/schemas/Txid" }, { "type": "null" } ] } }, "additionalProperties": false }, "EndedListingSale": { "type": "object", "required": [ "txid", "price_sats", "proceeds_sats", "confirmed" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "proceeds_sats": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ], "description": "The seller's asset proceeds: the price on a listing sale (the buyer pays the marketplace fee); null on an offer sale, whose deducted fees are not stored." }, "confirmed": { "type": "boolean" } }, "additionalProperties": false }, "PublicOffer": { "type": "object", "required": [ "id", "bid_txid", "bid_vout", "funding_slot_id", "price_sats", "scope", "bidder", "created_at", "expires_at" ], "properties": { "id": { "type": "string" }, "bid_txid": { "$ref": "#/components/schemas/Txid" }, "bid_vout": { "type": "integer", "minimum": 0 }, "funding_slot_id": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "bidder": { "$ref": "#/components/schemas/BitcoinAddress" }, "created_at": { "type": "integer" }, "expires_at": { "type": "integer" }, "target_txid": { "type": [ "string", "null" ] }, "target_vout": { "type": [ "integer", "null" ] } }, "additionalProperties": false }, "DirectOffer": { "allOf": [ { "$ref": "#/components/schemas/PublicOffer" }, { "type": "object", "required": [ "target_txid", "target_vout" ], "properties": { "target_txid": { "$ref": "#/components/schemas/Txid" }, "target_vout": { "type": "integer", "minimum": 0 } } } ] }, "MarketEvent": { "type": "object", "required": [ "event_id", "kind", "at", "reason", "asset", "asset_longname", "collection", "price_sats", "seller", "buyer", "bidder", "txid", "fill_kind", "confirmed_at" ], "additionalProperties": false, "properties": { "event_id": { "type": "string", "description": "Stable per (kind, subject)." }, "kind": { "type": "string", "enum": [ "sale", "listed", "delisted", "offer_placed", "offer_ended", "collection_offer_placed", "collection_offer_ended" ] }, "at": { "type": "integer", "description": "Unix seconds: a sale's broadcast, a placement's creation, an ending's retirement (a derived expiry carries its expires_at)." }, "reason": { "type": [ "string", "null" ], "enum": [ "owner", "expired", "invalid", "cancelled", "superseded", "filled", null ], "description": "Why a delisted or *_ended event ended; null on every other kind." }, "asset": { "type": [ "string", "null" ], "description": "Null for a collection-scoped offer." }, "asset_longname": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ], "description": "A collection offer's collection slug." }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "seller": { "type": [ "string", "null" ] }, "buyer": { "type": [ "string", "null" ], "description": "A sale's buyer (its delivery address)." }, "bidder": { "type": [ "string", "null" ] }, "txid": { "oneOf": [ { "$ref": "#/components/schemas/Txid" }, { "type": "null" } ], "description": "The settlement transaction, on sales." }, "fill_kind": { "type": [ "string", "null" ], "enum": [ "listing", "offer", null ] }, "confirmed_at": { "type": [ "integer", "null" ] } } }, "FillActivity": { "type": "object", "required": [ "txid", "kind", "ref_id", "asset", "seller", "buyer", "price_sats", "platform_fee_sats", "delivery_mode", "broadcast_at", "confirmed_at", "block_index" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "kind": { "type": "string" }, "ref_id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "asset_longname": { "type": [ "string", "null" ] }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "buyer": { "$ref": "#/components/schemas/BitcoinAddress" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "platform_fee_sats": { "type": "integer", "minimum": 0 }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ] }, "broadcast_at": { "type": "integer" }, "confirmed_at": { "type": [ "integer", "null" ] }, "block_index": { "type": [ "integer", "null" ] } }, "additionalProperties": false }, "AttachedUtxo": { "type": "object", "required": [ "txid", "vout", "holder", "quantity_raw", "updated_block_index" ], "properties": { "txid": { "type": "string" }, "vout": { "type": "integer", "minimum": 0 }, "holder": { "type": [ "string", "null" ] }, "quantity_raw": { "$ref": "#/components/schemas/RawQuantity" }, "updated_block_index": { "type": "integer", "minimum": 0 } } }, "AssetBook": { "type": "object", "required": [ "asks", "bids", "listings", "offers", "direct_offers", "fills", "utxos" ], "properties": { "utxos": { "type": "array", "items": { "$ref": "#/components/schemas/AttachedUtxo" } }, "asks": { "type": "array", "items": { "$ref": "#/components/schemas/BookLevel" } }, "bids": { "type": "array", "items": { "$ref": "#/components/schemas/BookLevel" } }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/PublicListing" } }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOffer" }, "description": "Offers any holder of the asset can fill (asset-wide offers and collection/trait policies this asset satisfies), best first. Never includes unit-targeted offers." }, "direct_offers": { "description": "Asset offers bound to one exact attached unit of this asset (target_txid:target_vout), best first, at most 50. Only that unit's holder can accept one; they never count toward bids.", "type": "array", "items": { "$ref": "#/components/schemas/DirectOffer" } }, "fills": { "type": "array", "items": { "$ref": "#/components/schemas/FillActivity" } } }, "additionalProperties": false }, "CollectionBookListing": { "allOf": [ { "$ref": "#/components/schemas/PublicListing" }, { "type": "object", "required": [ "expires_at" ], "properties": { "expires_at": { "type": [ "integer", "null" ] } } } ] }, "CollectionBookOffer": { "type": "object", "required": [ "id", "bidder", "bid_txid", "bid_vout", "funding_slot_id", "price_sats", "scope", "kind", "asset", "collection", "max_supply_units", "min_supply_units", "issued_year", "series", "artist", "expires_at", "created_at" ], "properties": { "id": { "type": "string" }, "bidder": { "$ref": "#/components/schemas/BitcoinAddress" }, "bid_txid": { "$ref": "#/components/schemas/Txid" }, "bid_vout": { "type": "integer", "minimum": 0 }, "funding_slot_id": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "kind": { "type": "string", "enum": [ "asset", "collection", "trait" ] }, "asset": { "oneOf": [ { "$ref": "#/components/schemas/AssetId" }, { "type": "null" } ] }, "collection": { "type": [ "string", "null" ] }, "max_supply_units": { "type": [ "integer", "null" ], "minimum": 0 }, "min_supply_units": { "type": [ "integer", "null" ], "minimum": 0 }, "issued_year": { "type": [ "integer", "null" ] }, "series": { "type": [ "integer", "null" ] }, "artist": { "type": [ "string", "null" ] }, "expires_at": { "type": "integer" }, "created_at": { "type": "integer" } }, "additionalProperties": false }, "CollectionOfferLevel": { "type": "object", "required": [ "price_sats", "funded_slots", "scope", "kind", "asset", "collection", "max_supply_units", "min_supply_units", "issued_year", "series", "artist" ], "properties": { "price_sats": { "$ref": "#/components/schemas/Sats" }, "funded_slots": { "type": "integer", "minimum": 1 }, "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "kind": { "type": "string", "enum": [ "asset", "collection", "trait" ] }, "asset": { "oneOf": [ { "$ref": "#/components/schemas/AssetId" }, { "type": "null" } ] }, "collection": { "type": [ "string", "null" ] }, "max_supply_units": { "type": [ "integer", "null" ], "minimum": 0 }, "min_supply_units": { "type": [ "integer", "null" ], "minimum": 0 }, "issued_year": { "type": [ "integer", "null" ] }, "series": { "type": [ "integer", "null" ] }, "artist": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CollectionBook": { "type": "object", "required": [ "asks", "listings", "offer_levels", "offers", "fills", "top_collection_offer_sats", "best_offer_sats", "listings_truncated", "offer_levels_truncated", "offers_truncated" ], "properties": { "asks": { "type": "array", "items": { "$ref": "#/components/schemas/BookLevel" } }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionBookListing" } }, "offer_levels": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionOfferLevel" } }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionBookOffer" } }, "fills": { "type": "array", "items": { "$ref": "#/components/schemas/FillActivity" } }, "top_collection_offer_sats": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] }, "best_offer_sats": { "oneOf": [ { "$ref": "#/components/schemas/Sats" }, { "type": "null" } ] }, "listings_truncated": { "type": "boolean" }, "offer_levels_truncated": { "type": "boolean" }, "offers_truncated": { "type": "boolean" } }, "additionalProperties": false }, "AuthChallenge": { "type": "object", "required": [ "message", "issued_at", "expires_at" ], "properties": { "message": { "type": "string" }, "issued_at": { "type": "integer" }, "expires_at": { "type": "integer" } }, "additionalProperties": false }, "MarketplaceSession": { "type": "object", "required": [ "token", "address", "expires_at" ], "properties": { "token": { "type": "string" }, "address": { "$ref": "#/components/schemas/BitcoinAddress" }, "expires_at": { "type": "integer" } }, "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_request", "unsupported_address_type", "unauthenticated", "forbidden", "not_found", "method_not_allowed", "state_changed", "expired", "invalid_transaction", "rate_limited", "internal_error", "upstream_unavailable", "service_unavailable", "checkout_changed", "target_unavailable", "signature_invalid", "template_mismatch", "mempool_rejected", "broadcast_unknown", "conflict_spend", "duplicate_funding_slot", "offer_selection_unavailable", "attached_delivery_single_item_only", "insufficient_funds", "insufficient_asset_balance", "price_below_minimum", "listing_price_above_maximum", "counter_price_invalid", "self_trade", "offer_capacity_full", "open_offer_limit", "policy_offer_refused" ] }, "retryable": { "type": "boolean" }, "mempool_policy": { "type": "string", "enum": [ "fee_floor", "chain_too_long", "truc", "dust", "nonstandard" ], "description": "On 422 mempool_rejected from a broadcast: which deterministic node policy refused the bytes. Retrying the same bytes fails the same way. fee_floor: re-quote at a higher fee_rate. chain_too_long: too many unconfirmed ancestors; wait for a confirmation, then retry. truc: a version-3 (TRUC) package rule, such as spending an unconfirmed version-3 output; wait for a confirmation, then retry." }, "mempool_reason": { "type": "string", "description": "The node's own reject reason, on mempool_rejected (422) and on state_changed (409) when a broadcast lost to a conflicting or replacing spend." }, "wait_for_confirmation": { "type": "boolean", "description": "Present and true when mempool_policy is chain_too_long or truc." }, "claims_released": { "type": "boolean", "description": "On a checkout or accept completion refused as mempool_rejected: the journaled settlement ended and every listing, bid, and asset claim it held was released (its inputs were proven unspent). The quote or accept is replaced; request a new one." }, "refused_listings": { "type": "array", "description": "Batch listing routes only: every refused item. The first sets the status and code.", "items": { "$ref": "#/components/schemas/ListingBatchRefusal" } }, "retry_after_seconds": { "type": "integer", "minimum": 1, "description": "On 429 rate_limited: the exact seconds until the oldest counted request leaves the window; a retry then is admitted (also sent as Retry-After). Limited writes are bucketed per route scope in exact sliding 60-second windows: by session address when a valid x-session-token is present, otherwise by IP, with a per-IP ceiling across sessions. Expensive writes: 20, ceiling 120. Signed completions: 120, ceiling 600. Session minting (/auth/*): 60 per IP. A request refused by any bucket is counted by none." } }, "additionalProperties": true }, "Hex": { "type": "string", "pattern": "^[0-9a-f]+$" }, "Txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "BitcoinAddress": { "type": "string", "description": "Mainnet P2TR or P2WPKH address. The SIGNING capability: every signature is verified by reconstructing a BIP-143/BIP-341 witness sighash." }, "MessageSignatureVerification": { "oneOf": [ { "type": "object", "required": [ "method", "format" ], "properties": { "method": { "const": "BIP-322" }, "format": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "method", "format" ], "properties": { "method": { "const": "BIP-137" }, "format": { "const": "legacy_recoverable" } }, "additionalProperties": false } ], "description": "Explicit message-signature dialect. Omission preserves the original BIP-322 contract; BIP-137 is accepted only when declared as legacy_recoverable, except that a P2PKH address accepts a classic 65-byte BIP-137 signature or a two-item signature/public-key stack under any label." }, "DeliveryAddress": { "type": "string", "description": "Destination for a detached Counterparty balance. ANY address family Core accepts, legacy P2PKH included: a delivery address is a UTF-8 string inside the detach OP_RETURN, never a signer and never an output script. Deliberately wider than BitcoinAddress." }, "AssetSourceAddress": { "type": "string", "description": "Counterparty address whose balance is attached when a listing is prepared. P2PKH, P2WPKH, or P2TR: these spend families are supported by the attach verifier. The source owns input 0 and may differ from seller, which owns the modern asset UTXO and signs the listing." }, "AttachSigner": { "type": "object", "required": [ "address", "inputs_to_sign" ], "properties": { "address": { "$ref": "#/components/schemas/AssetSourceAddress" }, "inputs_to_sign": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "integer", "minimum": 0 } } }, "additionalProperties": false }, "AssetId": { "type": "string", "description": "Canonical compact Counterparty key. A subasset uses its A ID; asset_longname is display metadata." }, "RawQuantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "Sats": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "FeeRate": { "type": "number", "minimum": 0.1, "maximum": 500 }, "PlatformFeeInternalKey": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "x-only BIP86 internal key of the marketplace fee output, derived server-side from the fee allocation's own index (account m/86'/0'/1', child 0/index, without its parity byte). The fee output is exactly the key-path-only P2TR of this key. Absent when there is no key to vouch for (a pre-fee template, or a fee key that is not configured or no longer derives the stored output)." }, "Outpoint": { "type": "object", "required": [ "txid", "vout" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "CartLine": { "type": "object", "required": [ "asset", "quantity", "max_price_sats" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 20 }, "max_price_sats": { "$ref": "#/components/schemas/Sats" }, "target_outpoint": { "type": "object", "required": [ "txid", "vout" ], "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "vout": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "additionalProperties": false, "description": "Optional exact asset outpoint. Never substitutes another unit. Cart quantity must be 1; offers must have asset scope." } }, "additionalProperties": false }, "CartFillRequest": { "type": "object", "required": [ "items", "buyer_address" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/CartLine" } }, "buyer_address": { "$ref": "#/components/schemas/BitcoinAddress" }, "buyer_tap_internal_key": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "delivery_address": { "$ref": "#/components/schemas/DeliveryAddress" }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ], "default": "detached" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false }, "CounterFillRequest": { "type": "object", "required": [ "counter_id", "buyer_address" ], "properties": { "counter_id": { "type": "string" }, "buyer_address": { "$ref": "#/components/schemas/BitcoinAddress" }, "buyer_tap_internal_key": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "delivery_address": { "$ref": "#/components/schemas/DeliveryAddress" }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ], "default": "detached" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" } }, "additionalProperties": false }, "OfferTarget": { "type": "object", "description": "One alternative eligibility policy. Multiple targets sharing one bid outpoint are mutually exclusive choices, not additional capacity.", "required": [ "scope" ], "properties": { "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "asset": { "$ref": "#/components/schemas/AssetId" }, "collection": { "type": "string" }, "max_supply_units": { "type": [ "integer", "null" ] }, "min_supply_units": { "type": [ "integer", "null" ] }, "issued_year": { "type": [ "integer", "null" ] }, "series": { "type": [ "integer", "null" ] }, "artist": { "type": [ "string", "null" ] }, "target_outpoint": { "type": "object", "required": [ "txid", "vout" ], "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "vout": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "additionalProperties": false, "description": "Optional exact asset outpoint. Never substitutes another unit. Cart quantity must be 1; offers must have asset scope." } }, "additionalProperties": false }, "OfferFundingPreflightEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/OfferFundingPreflight" } }, "additionalProperties": false }, "OfferFundingPreflight": { "type": "object", "required": [ "bidder", "funding", "price_sats", "asset_free" ], "properties": { "bidder": { "$ref": "#/components/schemas/BitcoinAddress" }, "funding": { "type": "object", "required": [ "txid", "vout", "value_sats" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 }, "value_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "platform_fee_sats": { "type": "integer", "const": 0, "description": "Marketplace fee pre-funded by the bidder: 0. The accepting seller pays the fee." }, "asset_free": { "const": true } }, "additionalProperties": false }, "PlaceOffers": { "type": "object", "x-max-expanded-offers": 1000, "description": "Creates the cross-product of exact-price funding outpoints and alternative targets. N bid outpoints provide capacity N; each outpoint may back every target, and its first fill retires all sibling policies over that outpoint. At most 1000 offer rows may be created per request.", "required": [ "bids", "targets", "expires_at" ], "properties": { "bids": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Exact-price BTC outpoints, one per independently fillable collectible unit.", "items": { "$ref": "#/components/schemas/Outpoint" } }, "targets": { "type": "array", "minItems": 1, "maxItems": 500, "description": "Alternative asset, collection, or trait policies shared by every supplied funding outpoint.", "items": { "$ref": "#/components/schemas/OfferTarget" } }, "expires_at": { "type": "integer" }, "receive_address": { "$ref": "#/components/schemas/DeliveryAddress" }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ], "default": "detached" } }, "additionalProperties": false }, "OfferAcceptanceSelection": { "type": "object", "description": "Ordered offer policy ids a seller intends to act on. A valid selection contains at most one policy per funding slot.", "required": [ "offer_ids" ], "properties": { "offer_ids": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false }, "TransactionRecovery": { "oneOf": [ { "type": "object", "required": [ "state", "confirmed" ], "additionalProperties": false, "properties": { "state": { "const": "known" }, "confirmed": { "type": "boolean" } } }, { "type": "object", "required": [ "state" ], "additionalProperties": false, "properties": { "state": { "enum": [ "unspent", "unknown" ] } } }, { "type": "object", "required": [ "state", "txids" ], "additionalProperties": false, "properties": { "state": { "const": "missing_parents" }, "txids": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/Txid" } } } }, { "type": "object", "required": [ "state", "txid", "confirmed" ], "additionalProperties": false, "properties": { "state": { "const": "conflicted" }, "txid": { "$ref": "#/components/schemas/Txid" }, "confirmed": { "type": "boolean" } } } ] }, "TransactionRelayEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "object", "required": [ "txid" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" } }, "additionalProperties": false } }, "additionalProperties": false }, "AttachTemplateEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/AttachTemplate" } }, "additionalProperties": false }, "AttachSpeedUpEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/AttachSpeedUp" } }, "additionalProperties": false }, "AttachSpeedUp": { "type": "object", "required": [ "parent_txid", "owner", "fee_rate", "change", "child", "fees", "final_change_sats" ], "properties": { "parent_txid": { "$ref": "#/components/schemas/Txid" }, "owner": { "$ref": "#/components/schemas/BitcoinAddress" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "change": { "type": "object", "description": "The attach's plain-BTC change output the child spends. Never the asset UTXO.", "required": [ "txid", "vout", "value_sats", "script_pub_key_hex" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 1 }, "value_sats": { "$ref": "#/components/schemas/Sats" }, "script_pub_key_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false }, "child": { "type": "object", "required": [ "psbt_hex", "expected_txid", "signing" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "expected_txid": { "$ref": "#/components/schemas/Txid" }, "signing": { "type": "object", "required": [ "signer_address", "inputs_to_sign", "sighash" ], "properties": { "signer_address": { "$ref": "#/components/schemas/BitcoinAddress" }, "inputs_to_sign": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "const": 0 } }, "sighash": { "const": "DEFAULT|ALL" } }, "additionalProperties": false } }, "additionalProperties": false }, "fees": { "type": "object", "required": [ "parent_fee_sats", "parent_vsize", "unconfirmed_ancestors", "child_fee_sats", "child_vsize", "package_fee_sats", "package_vsize", "package_fee_rate" ], "properties": { "parent_fee_sats": { "$ref": "#/components/schemas/Sats", "description": "The attach plus every unconfirmed ancestor it waits on." }, "parent_vsize": { "type": "integer", "minimum": 1 }, "unconfirmed_ancestors": { "type": "integer", "minimum": 0 }, "child_fee_sats": { "$ref": "#/components/schemas/Sats" }, "child_vsize": { "type": "integer", "minimum": 1 }, "package_fee_sats": { "$ref": "#/components/schemas/Sats" }, "package_vsize": { "type": "integer", "minimum": 1 }, "package_fee_rate": { "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "final_change_sats": { "$ref": "#/components/schemas/Sats", "description": "What the child returns to the owner: change minus the child fee." } }, "additionalProperties": false }, "AttachTemplate": { "type": "object", "required": [ "asset", "quantity_raw", "utxo_owner", "asset_source", "fee_rate", "attach", "txid_provisional", "asset_utxo", "funding_inputs", "change", "fees" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity_raw": { "$ref": "#/components/schemas/RawQuantity" }, "utxo_owner": { "$ref": "#/components/schemas/BitcoinAddress", "description": "The address that will own the asset UTXO." }, "asset_source": { "$ref": "#/components/schemas/AssetSourceAddress" }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "attach": { "type": "object", "required": [ "psbt_hex", "signers", "sighash", "expected_txid" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "signers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AttachSigner" } }, "sighash": { "const": "ALL" }, "expected_txid": { "$ref": "#/components/schemas/Txid" } }, "additionalProperties": false }, "txid_provisional": { "type": "boolean", "description": "True when a legacy input makes the txid unknowable before signing; a chained leg must compose from the signed parent." }, "asset_utxo": { "type": "object", "description": "Output 0 of the attach: the UTXO the unit lands on.", "required": [ "vout", "value_sats" ], "properties": { "vout": { "type": "integer", "minimum": 0 }, "value_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false }, "funding_inputs": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Outpoint" } }, "change": { "anyOf": [ { "type": "object", "required": [ "txid", "vout", "value_sats", "script_pub_key_hex" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 }, "value_sats": { "$ref": "#/components/schemas/Sats" }, "script_pub_key_hex": { "$ref": "#/components/schemas/Hex" } }, "additionalProperties": false }, { "type": "null" } ] }, "fees": { "$ref": "#/components/schemas/FeeBreakdown" } }, "additionalProperties": false }, "ListingPreflightEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/ListingPreflight" } }, "additionalProperties": false }, "ListingBatchRepricePreflight": { "type": "object", "required": [ "action", "listings" ], "additionalProperties": false, "properties": { "action": { "const": "reprice_preflight" }, "listings": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Distinct listing ids.", "items": { "type": "object", "required": [ "listing_id", "price_sats" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string", "minLength": 1 }, "price_sats": { "$ref": "#/components/schemas/Sats" } } } } } }, "ListingBatchReprice": { "type": "object", "required": [ "action", "listings" ], "additionalProperties": false, "properties": { "action": { "const": "reprice" }, "listings": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Distinct listing ids, each with its signed replacement listing PSBT.", "items": { "type": "object", "required": [ "listing_id", "psbt_hex" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string", "minLength": 1 }, "psbt_hex": { "$ref": "#/components/schemas/Hex" } } } } } }, "ListingBatchDelist": { "type": "object", "required": [ "action", "listings" ], "additionalProperties": false, "properties": { "action": { "const": "delist" }, "listings": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Distinct listing ids.", "items": { "type": "object", "required": [ "listing_id" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string", "minLength": 1 } } } } } }, "ListingRepricePreflightBatchEnvelope": { "type": "object", "required": [ "result" ], "additionalProperties": false, "properties": { "result": { "type": "object", "required": [ "listings" ], "additionalProperties": false, "properties": { "listings": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/ListingRepricePreflight" } } } } } }, "ListingBatchOutcomesEnvelope": { "type": "object", "required": [ "result" ], "additionalProperties": false, "properties": { "result": { "type": "object", "required": [ "listings" ], "additionalProperties": false, "properties": { "listings": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/ListingBatchItemOutcome" } } } } } }, "ListingBatchItemOutcome": { "oneOf": [ { "type": "object", "required": [ "listing_id", "ok" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string" }, "ok": { "const": true }, "price_sats": { "$ref": "#/components/schemas/Sats", "description": "Reprice only: the verified new price." } } }, { "type": "object", "required": [ "listing_id", "ok", "code", "error" ], "additionalProperties": false, "properties": { "listing_id": { "type": "string" }, "ok": { "const": false }, "code": { "const": "state_changed" }, "error": { "type": "string" } } } ] }, "ListingBatchRefusal": { "type": "object", "description": "One refused item in a batch refusal's `refused_listings` array. Nothing in the batch was changed.", "required": [ "index", "listing_id", "status", "code", "error" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "listing_id": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "error": { "type": "string" } }, "additionalProperties": true }, "OwnerEvent": { "type": "object", "required": [ "event_id", "kind", "at", "role", "status", "asset", "collection", "price_sats", "txid", "listing_id", "offer_id", "authorization_id", "parent_txid", "funding_slot_id", "asset_utxo" ], "additionalProperties": false, "properties": { "event_id": { "type": "string", "description": "Stable per (kind, subject). Dedupe on it." }, "kind": { "type": "string", "enum": [ "listing_filled", "listing_delisted", "listing_expired", "listing_invalidated", "offer_accepted", "offer_cancelled", "offer_expired", "offer_retired", "offer_consumed_by_counter", "exact_authorization_used", "exact_authorization_retired", "collection_offer_filled", "collection_offer_cancelled", "collection_offer_expired", "collection_offer_retired", "purchase_confirmed", "sale_confirmed" ] }, "at": { "type": "integer", "description": "When the market observed it (unix seconds); a derived expiry carries its expires_at." }, "role": { "type": "string", "enum": [ "seller", "bidder", "buyer" ] }, "status": { "type": "string", "description": "The subject row's own status now." }, "asset": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "txid": { "oneOf": [ { "$ref": "#/components/schemas/Txid" }, { "type": "null" } ], "description": "The settlement transaction, when there is one." }, "listing_id": { "type": [ "string", "null" ] }, "offer_id": { "type": [ "string", "null" ] }, "authorization_id": { "type": [ "string", "null" ] }, "parent_txid": { "oneOf": [ { "$ref": "#/components/schemas/Txid" }, { "type": "null" } ], "description": "A collection offer's funding parent (its id)." }, "funding_slot_id": { "type": [ "string", "null" ] }, "asset_utxo": { "oneOf": [ { "type": "object", "required": [ "txid", "vout" ], "additionalProperties": false, "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 } } }, { "type": "null" } ] } } }, "ListingRepricePreflightEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/ListingRepricePreflight" } }, "additionalProperties": false }, "ListingRepricePreflight": { "type": "object", "required": [ "operation_id", "protocol_version", "listing_id", "seller", "asset", "quantity_raw", "current_price_sats", "marketplace_expires_at", "asset_utxo", "listing", "expires_at" ], "properties": { "operation_id": { "type": "string" }, "protocol_version": { "const": "counterparty_attach_listing_v1" }, "listing_id": { "type": "string" }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity_raw": { "$ref": "#/components/schemas/RawQuantity" }, "current_price_sats": { "$ref": "#/components/schemas/Sats" }, "marketplace_expires_at": { "type": [ "integer", "null" ] }, "asset_utxo": { "allOf": [ { "$ref": "#/components/schemas/Outpoint" }, { "type": "object", "required": [ "utxo_value_sats" ], "properties": { "utxo_value_sats": { "$ref": "#/components/schemas/Sats" } } } ] }, "listing": { "type": "object", "required": [ "psbt_hex", "signer_address", "inputs_to_sign", "sighash", "price_sats" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "signer_address": { "$ref": "#/components/schemas/BitcoinAddress" }, "inputs_to_sign": { "type": "array", "items": { "type": "integer" } }, "sighash": { "const": "SINGLE|ANYONECANPAY" }, "price_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false }, "expires_at": { "type": "integer" } }, "additionalProperties": false }, "ListingPreflight": { "type": "object", "required": [ "id", "seller", "asset_source", "asset", "quantity_raw", "mode", "status", "asset_utxo", "fees", "expires_at" ], "properties": { "id": { "type": "string" }, "operation_id": { "type": "string" }, "protocol_version": { "const": "counterparty_attach_listing_v1" }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "asset_source": { "$ref": "#/components/schemas/AssetSourceAddress" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity_raw": { "$ref": "#/components/schemas/RawQuantity" }, "mode": { "type": "string", "enum": [ "reuse", "attach" ] }, "status": { "type": "string", "enum": [ "awaiting_attach_signature", "broadcasting", "awaiting_indexer", "prepared", "ready", "completed", "failed", "expired", "withdrawn" ], "description": "completed: the listing exists. withdrawn (read-time only): a reorg reopened the attach and withdrew its listing by design; the attach has been mined again, so the unit is attached and must be listed again with a new preflight (next_action list_again). A failed, expired, or re-verifying (awaiting_indexer) preflight keeps its own status even when a listing row exists." }, "asset_utxo": { "allOf": [ { "$ref": "#/components/schemas/Outpoint" }, { "type": "object", "required": [ "utxo_value_sats" ], "properties": { "utxo_value_sats": { "$ref": "#/components/schemas/Sats" } } } ] }, "fees": { "$ref": "#/components/schemas/FeeBreakdown" }, "listing": { "type": "object", "required": [ "psbt_hex", "signer_address", "inputs_to_sign", "sighash", "price_sats" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "signer_address": { "$ref": "#/components/schemas/BitcoinAddress" }, "inputs_to_sign": { "type": "array", "items": { "type": "integer" } }, "sighash": { "const": "SINGLE|ANYONECANPAY" }, "price_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false }, "attach": { "type": "object", "required": [ "psbt_hex", "signers", "sighash", "expected_txid" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "signers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AttachSigner" }, "description": "Canonical signer groups derived from authenticated PSBT prevouts. Input 0 belongs to asset_source; every input appears exactly once." }, "sighash": { "const": "ALL" }, "expected_txid": { "$ref": "#/components/schemas/Txid" } }, "additionalProperties": false }, "next_action": { "type": [ "string", "null" ], "enum": [ "sign_attach", "wait_for_indexer", "set_price", "sign_listing", "list_again", null ] }, "expires_at": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "bitcoin_confirmed_at": { "type": [ "integer", "null" ] }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" }, "listing_id": { "type": [ "string", "null" ] }, "listed_price_sats": { "type": [ "integer", "null" ], "description": "Accepted listing price when recovered by preflight ID." }, "listing_status": { "type": [ "string", "null" ], "description": "Current listing state, distinct from a completed preparation. Includes expiry derived at read time." } }, "additionalProperties": false }, "FeeBreakdown": { "type": "object", "required": [ "network", "protocol", "platform" ], "properties": { "network": { "type": "object", "required": [ "asset", "amount_sats" ], "properties": { "asset": { "const": "BTC" }, "amount_sats": { "type": "integer", "minimum": 0 } } }, "protocol": { "type": "object", "required": [ "asset", "amount_raw", "variable_until_confirmed" ], "properties": { "asset": { "const": "XCP" }, "amount_raw": { "$ref": "#/components/schemas/RawQuantity" }, "actual_amount_raw": { "oneOf": [ { "$ref": "#/components/schemas/RawQuantity" }, { "type": "null" } ] }, "observed_block": { "type": [ "integer", "null" ] }, "variable_until_confirmed": { "type": "boolean" }, "charged_at": { "type": [ "string", "null" ] } } }, "platform": { "type": "object", "required": [ "asset", "amount_sats" ], "properties": { "asset": { "const": "BTC" }, "amount_sats": { "type": "integer", "minimum": 0 } } } }, "additionalProperties": false }, "FillQuoteEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/FillQuote" } }, "additionalProperties": false }, "FillQuote": { "type": "object", "required": [ "operation_id", "protocol_version", "fill_id", "psbt_hex", "expected_txid", "signing", "selected_outpoints", "settlement_items", "fee_rate", "subtotal_sats", "network_fee_sats", "platform_fee_sats", "total_sats", "delivery", "expires_at", "reserves_inventory" ], "properties": { "operation_id": { "type": "string" }, "protocol_version": { "const": "direct_v1" }, "fill_id": { "type": "string" }, "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "expected_txid": { "$ref": "#/components/schemas/Txid" }, "signing": { "type": "object", "required": [ "signer_address", "inputs_to_sign", "sighash" ], "properties": { "signer_address": { "$ref": "#/components/schemas/BitcoinAddress" }, "inputs_to_sign": { "type": "array", "items": { "type": "integer", "minimum": 0 } }, "sighash": { "const": "ALL" } }, "additionalProperties": false }, "selected_outpoints": { "type": "object", "required": [ "funding", "assets" ], "properties": { "funding": { "type": "array", "items": { "$ref": "#/components/schemas/Outpoint" } }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Outpoint" } } }, "additionalProperties": false }, "settlement_items": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "listing_id", "asset", "quantity_raw", "seller", "outpoint", "utxo_value_sats", "price_sats", "seller_payment_sats" ], "properties": { "listing_id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/AssetId" }, "quantity_raw": { "type": "string", "pattern": "^[0-9]+$" }, "seller": { "$ref": "#/components/schemas/BitcoinAddress" }, "outpoint": { "$ref": "#/components/schemas/Outpoint" }, "utxo_value_sats": { "type": "integer", "minimum": 1 }, "price_sats": { "$ref": "#/components/schemas/Sats" }, "seller_payment_sats": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "fee_rate": { "$ref": "#/components/schemas/FeeRate" }, "subtotal_sats": { "$ref": "#/components/schemas/Sats" }, "network_fee_sats": { "type": "integer", "minimum": 0 }, "platform_fee_sats": { "type": "integer", "minimum": 0 }, "platform_fee_internal_key": { "$ref": "#/components/schemas/PlatformFeeInternalKey" }, "total_sats": { "$ref": "#/components/schemas/Sats" }, "change_sats": { "type": "integer", "minimum": 0 }, "delivery": { "type": "object", "required": [ "mode", "address", "defaulted", "settlement_groups" ], "properties": { "mode": { "type": "string", "enum": [ "detached", "attached" ] }, "address": { "$ref": "#/components/schemas/BitcoinAddress" }, "defaulted": { "type": "boolean" }, "utxo_value_sats": { "type": "integer", "const": 330 }, "settlement_groups": { "const": 1 } }, "additionalProperties": false }, "expires_at": { "type": "integer" }, "reserves_inventory": { "const": false } }, "additionalProperties": false }, "OfferFundingTemplateEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "$ref": "#/components/schemas/OfferFundingTemplate" } }, "additionalProperties": false }, "OfferFundingTemplate": { "type": "object", "required": [ "bidder", "price_sats", "platform_fee_sats", "delivery_mode", "slot_value_sats", "slot_count", "fee_rate_sat_vb", "funding_value_sats", "network_fee_sats", "change_sats", "inputs", "slots", "funding" ], "properties": { "bidder": { "$ref": "#/components/schemas/BitcoinAddress" }, "price_sats": { "$ref": "#/components/schemas/Sats", "description": "Offer price per slot; at least 5,000 sats." }, "platform_fee_sats": { "type": "integer", "const": 0, "description": "Marketplace fee pre-funded in each slot: always 0. The seller who accepts is the taker and pays platformFeeSats(price) out of their proceeds." }, "delivery_mode": { "type": "string", "enum": [ "detached", "attached" ] }, "slot_value_sats": { "$ref": "#/components/schemas/Sats", "description": "Actual value of each bid output: exactly price_sats, plus a 330 sat asset UTXO for attached delivery. No marketplace fee is pre-funded." }, "slot_count": { "type": "integer", "minimum": 1, "maximum": 20 }, "fee_rate_sat_vb": { "$ref": "#/components/schemas/FeeRate" }, "funding_value_sats": { "$ref": "#/components/schemas/Sats" }, "network_fee_sats": { "$ref": "#/components/schemas/Sats" }, "change_sats": { "type": "integer", "minimum": 0 }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "txid", "vout", "value_sats" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 }, "value_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false }, "description": "The bidder's asset-free inputs the template spends." }, "slots": { "type": "array", "items": { "type": "object", "required": [ "txid", "vout", "value_sats" ], "properties": { "txid": { "$ref": "#/components/schemas/Txid" }, "vout": { "type": "integer", "minimum": 0 }, "value_sats": { "$ref": "#/components/schemas/Sats" } }, "additionalProperties": false }, "description": "The bid outpoints the transaction creates: vout 0..slot_count-1, each worth slot_value_sats." }, "funding": { "type": "object", "required": [ "psbt_hex", "signers", "sighash", "expected_txid" ], "properties": { "psbt_hex": { "$ref": "#/components/schemas/Hex" }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/AttachSigner" } }, "sighash": { "const": "ALL" }, "expected_txid": { "$ref": "#/components/schemas/Txid" } }, "additionalProperties": false } }, "additionalProperties": false }, "ArtistProfileInput": { "type": "object", "required": [ "name", "slug", "bio", "website", "x_url", "version" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "slug": { "type": "string", "maxLength": 200 }, "bio": { "type": "string", "maxLength": 500 }, "website": { "type": "string", "maxLength": 500 }, "x_url": { "type": "string", "maxLength": 500 }, "version": { "type": "integer", "minimum": 0 } } }, "ArtistEditability": { "type": "object", "required": [ "eligible", "controlled", "total", "largest", "tied", "checked_height", "checked_hash" ], "properties": { "controlled": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "largest": { "type": "integer", "minimum": 0 }, "checked_height": { "type": "integer", "minimum": 0 }, "eligible": { "type": "boolean" }, "tied": { "type": "boolean" }, "checked_hash": { "type": "string" } } }, "ArtistEditEnvelope": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "object", "required": [ "artist", "access" ], "properties": { "artist": { "$ref": "#/components/schemas/ArtistDetail" }, "access": { "$ref": "#/components/schemas/ArtistEditability" } } } } }, "ArtistPreviewAsset": { "type": "object", "required": [ "asset", "asset_longname", "issued_year", "media_kind", "protocol_subtype", "collection", "collection_name", "art_frame" ], "properties": { "asset": { "type": "string" }, "asset_longname": { "type": [ "string", "null" ] }, "issued_year": { "type": [ "integer", "null" ] }, "media_kind": { "type": [ "string", "null" ], "enum": [ "image", "animation", "video", "html", "svg", null ] }, "protocol_subtype": { "type": [ "string", "null" ] }, "collection": { "type": "string" }, "collection_name": { "type": "string" }, "art_frame": { "type": "string", "enum": [ "card", "square", "landscape" ] } }, "additionalProperties": false }, "WireAttachableAssetResult": { "type": "object", "properties": { "asset": { "type": "string" }, "asset_longname": { "type": [ "string", "null" ] }, "collection": { "type": "string" }, "divisible": { "type": "number" }, "protocol_subtype": { "type": [ "string", "null" ], "description": "Global Bitcoin Stamps subtype, independent of collection membership." }, "media_kind": { "anyOf": [ { "$ref": "#/components/schemas/WireMediaKind" }, { "type": "null" } ], "description": "Indexed media behavior used by every inventory presentation." }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" }, "units": { "type": "number" } }, "required": [ "asset", "asset_longname", "collection", "divisible", "media_kind", "protocol_subtype", "quantity_raw", "units" ], "description": "Address-level Counterparty balance that can be attached for listing.", "x-generated-wire-type": "AttachableAssetResult" }, "WireBidderOffer": { "type": "object", "properties": { "target_txid": { "type": [ "string", "null" ] }, "target_vout": { "type": [ "number", "null" ] }, "id": { "type": "string" }, "bid_txid": { "type": "string" }, "bid_vout": { "type": "number" }, "funding_slot_id": { "type": "string" }, "placement_id": { "type": [ "string", "null" ] }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "asset": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "expires_at": { "type": "number" }, "created_at": { "type": "number" }, "max_supply_units": { "type": [ "number", "null" ], "description": "Collection trait predicates; absent from an API that predates them." }, "min_supply_units": { "type": [ "number", "null" ] }, "issued_year": { "type": [ "number", "null" ] }, "series": { "type": [ "number", "null" ] }, "artist": { "type": [ "string", "null" ] }, "receive_address": { "type": [ "string", "null" ], "description": "Where a won asset is delivered (any Counterparty address family)." }, "bid_value_sats": { "anyOf": [ { "$ref": "#/components/schemas/WireSatoshis" }, { "type": "null" } ], "description": "The slot's exact value on chain: the funds the offer holds." }, "fill_txid": { "type": [ "string", "null" ], "description": "The settling transaction once this offer filled." } }, "required": [ "id", "bid_txid", "bid_vout", "funding_slot_id", "placement_id", "price_sats", "scope", "asset", "collection", "status", "expires_at", "created_at" ], "x-generated-wire-type": "BidderOffer" }, "WireBidderPolicyOffer": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "asset": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "max_supply_units": { "type": [ "number", "null" ] }, "min_supply_units": { "type": [ "number", "null" ] }, "issued_year": { "type": [ "number", "null" ] }, "series": { "type": [ "number", "null" ] }, "artist": { "type": [ "string", "null" ] }, "protocol_version": { "type": "string", "const": "funded_policy_offer_v1" }, "parent_txid": { "type": "string" }, "funding_slot_id": { "type": "string", "description": "\":\": alternatives sharing it are exclusive." }, "bidder": { "type": "string" }, "kind": { "$ref": "#/components/schemas/WirePolicyOfferKind" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "offer_value_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "expires_at": { "type": "number" }, "parent_vsize": { "type": "number" }, "parent_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "created_at": { "type": "number" }, "estimate": { "anyOf": [ { "$ref": "#/components/schemas/WirePolicyOfferNetEstimate" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/WireBidderPolicyOfferStatus" }, "funding_id": { "type": "string" }, "funding_status": { "$ref": "#/components/schemas/WirePolicyFundingStatus" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "const": "detached" }, "address": { "type": "string" } }, "required": [ "mode", "address" ] }, "market_key_exposure_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "fill_txid": { "type": [ "string", "null" ], "description": "The settling transaction once this alternative filled; absent from an API that predates it." } }, "required": [ "artist", "asset", "bidder", "collection", "created_at", "delivery", "estimate", "expires_at", "funding_id", "funding_slot_id", "funding_status", "issued_year", "kind", "market_key_exposure_sats", "max_supply_units", "min_supply_units", "offer_value_sats", "parent_fee_sats", "parent_txid", "parent_vsize", "price_sats", "protocol_version", "scope", "series", "status" ], "x-generated-wire-type": "BidderPolicyOffer" }, "WireBidderPolicyOfferStatus": { "type": "string", "enum": [ "active", "expired", "pending", "filled", "superseded", "cancelled", "invalid" ], "x-generated-wire-type": "BidderPolicyOfferStatus" }, "WireChargeSet": { "type": "object", "properties": { "network": { "type": "object", "properties": { "asset": { "type": "string", "const": "BTC" }, "amount_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "asset", "amount_sats" ] }, "protocol": { "type": "object", "properties": { "asset": { "type": "string", "const": "XCP" }, "amount_raw": { "type": "string" }, "actual_amount_raw": { "type": [ "string", "null" ] }, "observed_block": { "type": [ "number", "null" ] }, "variable_until_confirmed": { "type": "boolean" }, "charged_at": { "type": [ "string", "null" ] } }, "required": [ "asset", "amount_raw", "actual_amount_raw", "observed_block", "variable_until_confirmed", "charged_at" ] }, "platform": { "type": "object", "properties": { "asset": { "type": "string", "const": "BTC" }, "amount_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "asset", "amount_sats" ] } }, "required": [ "network", "protocol", "platform" ], "x-generated-wire-type": "ChargeSet" }, "WireCounterListingResult": { "type": "object", "properties": { "id": { "type": "string" }, "authorization_id": { "type": "string" }, "asset": { "type": "string" }, "seller": { "type": "string" }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "offer_price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "private_to": { "type": "string" }, "counter_of": { "type": "string" }, "funding_slot_id": { "type": "string" }, "utxo_txid": { "type": "string" }, "utxo_vout": { "type": "number" }, "expires_at": { "type": "number" }, "created_at": { "type": "number" } }, "required": [ "id", "authorization_id", "asset", "seller", "quantity_raw", "price_sats", "offer_price_sats", "private_to", "counter_of", "funding_slot_id", "utxo_txid", "utxo_vout", "expires_at", "created_at" ], "x-generated-wire-type": "CounterListingResult" }, "WireCounterOffer": { "type": "object", "properties": { "id": { "type": "string" }, "asset": { "type": "string" }, "seller": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "counter_of": { "type": "string" }, "offer_price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "expires_at": { "type": "number" }, "created_at": { "type": "number" } }, "required": [ "id", "asset", "seller", "price_sats", "counter_of", "offer_price_sats", "expires_at", "created_at" ], "x-generated-wire-type": "CounterOffer" }, "WireCounterPreflightResult": { "type": "object", "properties": { "operation_id": { "type": "string" }, "protocol_version": { "type": "string", "const": "counterparty_attach_listing_v1" }, "seller": { "type": "string" }, "asset": { "type": "string" }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" }, "asset_utxo": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "txid", "vout", "utxo_value_sats" ] }, "expires_at": { "type": "number", "description": "Deadline for reviewing this template. The listing itself has no Bitcoin-level expiry." }, "listing": { "$ref": "#/components/schemas/WireListingSigningInstruction" }, "authorization_id": { "type": "string" }, "offer_id": { "type": "string" }, "bidder": { "type": "string" }, "offer_price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "marketplace_expires_at": { "type": "number" } }, "required": [ "asset", "asset_utxo", "authorization_id", "bidder", "expires_at", "listing", "marketplace_expires_at", "offer_id", "offer_price_sats", "operation_id", "protocol_version", "quantity_raw", "seller" ], "x-generated-wire-type": "CounterPreflightResult" }, "WireDeliveryMode": { "type": "string", "enum": [ "detached", "attached" ], "x-generated-wire-type": "DeliveryMode" }, "WireExactOfferAcceptanceResult": { "type": "object", "properties": { "txid": { "type": "string" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "cpfp_txid": { "type": [ "string", "null" ] }, "delivery": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "address": { "type": "string" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "mode", "address" ] }, "requires_buyer_action": { "type": "boolean", "const": false }, "already_completed": { "type": "boolean", "const": true } }, "required": [ "txid", "seller_proceeds_sats", "network_fee_sats", "platform_fee_sats", "cpfp_txid", "delivery", "requires_buyer_action" ], "x-generated-wire-type": "ExactOfferAcceptanceResult" }, "WireExactOfferAcceptanceStatusResult": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "offer_id": { "type": "string" }, "funding_slot_id": { "type": "string" }, "bidder": { "type": "string" }, "seller": { "type": "string" }, "asset": { "type": "string" }, "target_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] }, "status": { "$ref": "#/components/schemas/WireExactOfferAuthorizationStatus" }, "txid": { "type": [ "string", "null" ] }, "cpfp_txid": { "type": [ "string", "null" ] }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "delivery": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "address": { "type": "string" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "mode", "address" ] }, "expires_at": { "type": "number" }, "created_at": { "type": "number" }, "settlement": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/WireSettlementStatus" }, "expected_txid": { "type": "string" }, "broadcast_txid": { "type": [ "string", "null" ] }, "attempts": { "type": "number" }, "last_error": { "type": [ "string", "null" ] }, "last_attempt_at": { "type": [ "number", "null" ] } }, "required": [ "status", "expected_txid", "broadcast_txid", "attempts", "last_error", "last_attempt_at" ] } ] }, "requires_buyer_action": { "type": "boolean", "const": false } }, "required": [ "authorization_id", "offer_id", "funding_slot_id", "bidder", "seller", "asset", "target_outpoint", "status", "txid", "cpfp_txid", "seller_proceeds_sats", "network_fee_sats", "platform_fee_sats", "delivery", "expires_at", "created_at", "settlement", "requires_buyer_action" ], "x-generated-wire-type": "ExactOfferAcceptanceStatusResult" }, "WireExactOfferActivationResult": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "status": { "type": "string", "const": "active" }, "expires_at": { "type": "number" }, "signature_validity": { "$ref": "#/components/schemas/WirePresignedAuthorizationValidity" } }, "required": [ "authorization_id", "status", "expires_at", "signature_validity" ], "x-generated-wire-type": "ExactOfferActivationResult" }, "WireExactOfferAuthorizationBatchResult": { "type": "object", "properties": { "protocol_version": { "type": "string", "const": "exact_offer_v1" }, "offer_id": { "type": "string" }, "funding_slot_id": { "type": "string" }, "target_count": { "type": "number" }, "authorizations": { "type": "array", "items": { "$ref": "#/components/schemas/WireExactOfferAuthorizationResult" } }, "reserves_funding": { "type": "boolean", "const": false }, "coverage": { "type": "object", "properties": { "mode": { "type": "string", "const": "explicit_outpoint_snapshot" }, "auto_authorizes_future_matches": { "type": "boolean", "const": false }, "refresh_action": { "type": "string", "const": "create_new_authorization_batch" } }, "required": [ "mode", "auto_authorizes_future_matches", "refresh_action" ] } }, "required": [ "protocol_version", "offer_id", "funding_slot_id", "target_count", "authorizations", "reserves_funding", "coverage" ], "x-generated-wire-type": "ExactOfferAuthorizationBatchResult" }, "WireExactOfferAuthorizationCancellationResult": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "cancelled": { "type": "boolean", "const": true }, "marketplace_access_revoked": { "type": "boolean", "const": true }, "bitcoin_authorization_invalidated": { "type": "boolean" }, "funding_spend_required": { "type": "boolean" }, "funding_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] } }, "required": [ "authorization_id", "cancelled", "marketplace_access_revoked", "bitcoin_authorization_invalidated", "funding_spend_required", "funding_outpoint" ], "x-generated-wire-type": "ExactOfferAuthorizationCancellationResult" }, "WireExactOfferAuthorizationResult": { "type": "object", "properties": { "operation_id": { "type": "string" }, "protocol_version": { "type": "string", "const": "exact_offer_v1" }, "authorization_id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_bidder", "active" ] }, "funding_slot_id": { "type": "string" }, "bidder": { "type": "string" }, "psbt_hex": { "type": "string", "description": "Always the UNSIGNED settlement template, for both roles. The buyer's input-0 signature is never served to the seller; the market merges it server-side when the seller submits input 1." }, "expected_txid": { "type": "string" }, "signing": { "$ref": "#/components/schemas/WireSigningInstruction" }, "target": { "type": "object", "properties": { "asset": { "type": "string" }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" }, "seller": { "type": "string" }, "outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] } }, "required": [ "asset", "quantity_raw", "seller", "outpoint" ] }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_internal_key": { "type": "string", "description": "Hex x-only BIP86 internal key of the marketplace fee output, derived server-side from the fee allocation's own index. The fee output is exactly the key-path-only P2TR of this key; a wallet that reads it checks that match and shows the fee payment either way. Absent when there is no key to vouch for (a pre-fee template or an unconfigured/rotated key)." }, "prefunded_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "fee_rate": { "type": "number" }, "delivery": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "address": { "type": "string" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "mode", "address" ] }, "signature_validity": { "$ref": "#/components/schemas/WirePresignedAuthorizationValidity" }, "fee_adjustment": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "ready" }, "signed_parent_fee_rate": { "type": "number" }, "current_target_fee_rate": { "type": "number" }, "parent_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "package_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "package_fee_rate": { "type": "number" }, "final_seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "state", "signed_parent_fee_rate", "current_target_fee_rate", "parent_fee_sats", "package_fee_sats", "package_fee_rate", "final_seller_proceeds_sats" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "seller_cpfp_required" }, "signed_parent_fee_rate": { "type": "number" }, "current_target_fee_rate": { "type": "number" }, "parent_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "child_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "package_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "package_fee_rate": { "type": "number" }, "final_seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "package_submission": { "type": "string", "enum": [ "submitpackage", "sequential_fallback" ] } }, "required": [ "state", "signed_parent_fee_rate", "current_target_fee_rate", "parent_fee_sats", "child_fee_sats", "package_fee_sats", "package_fee_rate", "final_seller_proceeds_sats", "package_submission" ] }, { "type": "object", "properties": { "state": { "type": "string", "const": "unavailable" }, "signed_parent_fee_rate": { "type": "number" }, "current_target_fee_rate": { "type": "number" }, "parent_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "final_seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "reason": { "type": "string" } }, "required": [ "state", "signed_parent_fee_rate", "current_target_fee_rate", "parent_fee_sats", "final_seller_proceeds_sats", "reason" ] } ] }, "cpfp": { "type": "object", "properties": { "psbt_hex": { "type": "string" }, "expected_txid": { "type": "string" }, "signing": { "$ref": "#/components/schemas/WireSigningInstruction" } }, "required": [ "psbt_hex", "expected_txid", "signing" ] }, "expires_at": { "type": "number" }, "reserves_funding": { "type": "boolean", "const": false }, "requires_buyer_action": { "type": "boolean", "const": false } }, "required": [ "operation_id", "protocol_version", "authorization_id", "status", "funding_slot_id", "bidder", "psbt_hex", "expected_txid", "signing", "target", "price_sats", "seller_proceeds_sats", "network_fee_sats", "platform_fee_sats", "prefunded_fee_sats", "fee_rate", "delivery", "signature_validity", "expires_at" ], "x-generated-wire-type": "ExactOfferAuthorizationResult" }, "WireExactOfferAuthorizationStatus": { "type": "string", "enum": [ "awaiting_bidder", "active", "settling", "completed", "cancelled", "invalid" ], "x-generated-wire-type": "ExactOfferAuthorizationStatus" }, "WireExactOfferSummary": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "offer_id": { "type": "string" }, "funding_slot_id": { "type": "string" }, "asset": { "type": "string" }, "bidder": { "type": "string" }, "seller": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "prefunded_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "fee_rate": { "type": "number" }, "expires_at": { "type": "number" }, "requires_buyer_action": { "type": "boolean", "const": false } }, "required": [ "authorization_id", "offer_id", "funding_slot_id", "asset", "bidder", "seller", "price_sats", "seller_proceeds_sats", "network_fee_sats", "platform_fee_sats", "prefunded_fee_sats", "fee_rate", "expires_at", "requires_buyer_action" ], "x-generated-wire-type": "ExactOfferSummary" }, "WireFillCompletionResult": { "type": "object", "properties": { "txid": { "type": "string" }, "already_completed": { "type": "boolean", "const": true } }, "required": [ "txid" ], "x-generated-wire-type": "FillCompletionResult" }, "WireFillRequestStatus": { "type": "string", "enum": [ "open", "completed", "replaced" ], "x-generated-wire-type": "FillRequestStatus" }, "WireFillStatusResult": { "type": "object", "properties": { "fill_id": { "type": "string" }, "buyer": { "type": "string" }, "status": { "$ref": "#/components/schemas/WireFillRequestStatus" }, "txid": { "type": [ "string", "null" ] }, "subtotal_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "delivery": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "address": { "type": "string" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "mode", "address" ] }, "expires_at": { "type": "number" }, "created_at": { "type": "number" }, "settlement": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/WireSettlementStatus" }, "expected_txid": { "type": "string" }, "broadcast_txid": { "type": [ "string", "null" ] }, "attempts": { "type": "number" }, "last_error": { "type": [ "string", "null" ] }, "last_attempt_at": { "type": [ "number", "null" ] } }, "required": [ "status", "expected_txid", "broadcast_txid", "attempts", "last_error", "last_attempt_at" ] } ] } }, "required": [ "fill_id", "buyer", "status", "txid", "subtotal_sats", "network_fee_sats", "platform_fee_sats", "delivery", "expires_at", "created_at", "settlement" ], "x-generated-wire-type": "FillStatusResult" }, "WireFundedAuthorizationTemplatesResult": { "type": "object", "properties": { "protocol_version": { "type": "string", "const": "exact_offer_v1" }, "funding_txid": { "type": "string", "description": "The funding template's (unsigned, witness-only) txid." }, "funding_slot_id": { "type": "string" }, "fee_rate": { "type": "number" }, "target_count": { "type": "number" }, "authorizations": { "type": "array", "items": { "$ref": "#/components/schemas/WireExactOfferAuthorizationResult" } }, "stored": { "type": "boolean", "const": false }, "reserves_funding": { "type": "boolean", "const": false } }, "required": [ "protocol_version", "funding_txid", "funding_slot_id", "fee_rate", "target_count", "authorizations", "stored", "reserves_funding" ], "description": "Exact-offer authorization templates over one set-aside output of an offer funding template that is not broadcast yet, for a wallet review that signs the funding and these authorizations together. Nothing is stored: after placing the offer with the signed funding, create the authorization batch with `fee_rate` set to this `fee_rate`; unchanged facts give byte-identical templates, so the signatures submit as they are. Each `authorization_id` here is a preview id, never a stored row.", "x-generated-wire-type": "FundedAuthorizationTemplatesResult" }, "WireFundedOfferPlacementResult": { "type": "object", "properties": { "placement_id": { "type": "string" }, "slot_count": { "type": "number" }, "target_count": { "type": "number" }, "offer_count": { "type": "number" }, "bidder": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "funding_slots": { "type": "array", "items": { "type": "object", "properties": { "funding_slot_id": { "type": "string" }, "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "funding_slot_id", "txid", "vout" ] } }, "offer_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/WireOfferTargetInput" } }, "expires_at": { "type": "number" }, "delivery": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "address": { "type": "string" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "mode", "address" ] }, "funding": { "type": "object", "properties": { "txid": { "type": "string" } }, "required": [ "txid" ] } }, "required": [ "bidder", "delivery", "expires_at", "funding", "funding_slots", "offer_count", "offer_ids", "placement_id", "platform_fee_sats", "price_sats", "slot_count", "target_count", "targets" ], "description": "A placement whose slots were minted by the relayed funding transaction.", "x-generated-wire-type": "FundedOfferPlacementResult" }, "WireInFlightPurchase": { "type": "object", "properties": { "fill_id": { "type": "string" }, "txid": { "type": "string" }, "status": { "type": "string", "enum": [ "prepared", "broadcast" ] }, "delivery_mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "intent": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cart" }, "items": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "quantity": { "type": "number" }, "max_price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "target_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] } }, "required": [ "asset", "quantity", "max_price_sats" ] } } }, "required": [ "kind", "items" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "counter" }, "counter_id": { "type": "string" } }, "required": [ "kind", "counter_id" ] }, { "type": "null" } ], "description": "What the buyer asked for: cart lines, or the counter being accepted." }, "listing_ids": { "type": "array", "items": { "type": "string" }, "description": "The listings this purchase takes: a page can show them as the buyer's own and pending while the public book (edge-cached) still lists them." }, "created_at": { "type": "number" } }, "required": [ "fill_id", "txid", "status", "delivery_mode", "intent", "listing_ids", "created_at" ], "description": "One of the buyer's purchases whose exact signed bytes the server has journaled and Bitcoin has not yet confirmed. `prepared`: the network has not been seen to accept the bytes yet (the server keeps relaying them, and new quotes never spend their coins). `broadcast`: accepted, waiting for a block.", "x-generated-wire-type": "InFlightPurchase" }, "WireListingAttachSigningInstruction": { "type": "object", "properties": { "psbt_hex": { "type": "string" }, "signers": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "inputs_to_sign": { "type": "array", "items": { "type": "number" } } }, "required": [ "address", "inputs_to_sign" ] }, "description": "Complete signer plan derived from authenticated PSBT prevouts. Input 0 must belong to the preflight's asset_source; later fee inputs may belong to other permissioned addresses in the same wallet." }, "sighash": { "type": "string", "const": "ALL" }, "expected_txid": { "type": "string" } }, "required": [ "psbt_hex", "signers", "sighash", "expected_txid" ], "x-generated-wire-type": "ListingAttachSigningInstruction" }, "WireListingDelistResult": { "type": "object", "properties": { "delisted": { "type": "boolean", "const": true } }, "required": [ "delisted" ], "x-generated-wire-type": "ListingDelistResult" }, "WireListingPreflightNextAction": { "type": [ "string", "null" ], "enum": [ "sign_attach", "wait_for_indexer", "set_price", "sign_listing", "list_again", null ], "x-generated-wire-type": "ListingPreflightNextAction" }, "WireListingPreflightResult": { "type": "object", "properties": { "operation_id": { "type": "string" }, "protocol_version": { "type": "string", "const": "counterparty_attach_listing_v1" }, "seller": { "type": "string" }, "asset": { "type": "string" }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" }, "asset_utxo": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "txid", "vout", "utxo_value_sats" ] }, "expires_at": { "type": "number", "description": "Deadline for reviewing this template. The listing itself has no Bitcoin-level expiry." }, "id": { "type": "string" }, "asset_source": { "type": "string", "description": "Address-level Counterparty balance consumed by the attach. It may be a Legacy sibling while seller owns the modern asset UTXO and listing." }, "mode": { "type": "string", "enum": [ "reuse", "attach" ] }, "status": { "$ref": "#/components/schemas/WireListingPreflightStatus" }, "fees": { "$ref": "#/components/schemas/WireChargeSet" }, "listing": { "$ref": "#/components/schemas/WireListingSigningInstruction" }, "attach": { "$ref": "#/components/schemas/WireListingAttachSigningInstruction" }, "next_action": { "$ref": "#/components/schemas/WireListingPreflightNextAction" }, "last_error": { "type": [ "string", "null" ] }, "bitcoin_confirmed_at": { "type": [ "number", "null" ] }, "created_at": { "type": "number" }, "updated_at": { "type": "number" }, "listing_id": { "type": [ "string", "null" ] }, "listed_price_sats": { "anyOf": [ { "$ref": "#/components/schemas/WireSatoshis" }, { "type": "null" } ], "description": "Actual accepted price when a submission is recovered by ID." }, "listing_status": { "type": [ "string", "null" ], "description": "Current listing state, distinct from successful preparation/submission." } }, "required": [ "asset", "asset_source", "asset_utxo", "bitcoin_confirmed_at", "created_at", "expires_at", "fees", "id", "last_error", "mode", "next_action", "operation_id", "protocol_version", "quantity_raw", "seller", "status", "updated_at" ], "x-generated-wire-type": "ListingPreflightResult" }, "WireListingPreflightStatus": { "type": "string", "enum": [ "awaiting_attach_signature", "broadcasting", "awaiting_indexer", "prepared", "ready", "completed", "failed", "expired", "withdrawn" ], "x-generated-wire-type": "ListingPreflightStatus" }, "WireListingRepriceResult": { "type": "object", "properties": { "id": { "type": "string" }, "price_sats": { "type": "integer", "minimum": 0, "maximum": 2100000000000000 } }, "required": [ "id", "price_sats" ], "description": "Small state-change responses shared by HTTP clients and the contract.", "x-generated-wire-type": "ListingRepriceResult" }, "WireListingResult": { "type": "object", "properties": { "id": { "type": "string" }, "asset": { "type": "string" }, "seller": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "utxo_txid": { "type": "string" }, "utxo_vout": { "type": "number" }, "expires_at": { "type": [ "number", "null" ] }, "preflight_id": { "type": "string" } }, "required": [ "id", "asset", "seller", "price_sats", "utxo_txid", "utxo_vout", "expires_at", "preflight_id" ], "x-generated-wire-type": "ListingResult" }, "WireListingSigningInstruction": { "type": "object", "properties": { "psbt_hex": { "type": "string" }, "signer_address": { "type": "string" }, "inputs_to_sign": { "type": "array", "items": { "type": "number" } }, "sighash": { "type": "string", "const": "SINGLE|ANYONECANPAY" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "psbt_hex", "signer_address", "inputs_to_sign", "sighash", "price_sats" ], "x-generated-wire-type": "ListingSigningInstruction" }, "WireMarketAnalytics": { "type": "object", "properties": { "as_of": { "type": "number" }, "since": { "type": "number" }, "market": { "type": "object", "properties": { "listings": { "type": "number" }, "asking_value_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "sellers": { "type": "number" }, "open_offers": { "type": "number" }, "bidders": { "type": "number" } }, "required": [ "listings", "asking_value_sats", "sellers", "open_offers", "bidders" ] }, "sales": { "type": "object", "properties": { "volume_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "sales": { "type": "number" }, "transactions": { "type": "number" }, "buyers": { "type": "number" }, "sellers": { "type": "number" } }, "required": [ "volume_sats", "sales", "transactions", "buyers", "sellers" ] }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "number" }, "volume_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "sales": { "type": "number" } }, "required": [ "day", "volume_sats", "sales" ] } }, "depth": { "type": "array", "items": { "type": "object", "properties": { "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "listings": { "type": "number" }, "offers": { "type": "number" } }, "required": [ "price_sats", "listings", "offers" ] }, "description": "Counts sampled at BTC price thresholds; one maximum price per funding slot." }, "sale_types": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "volume_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "sales": { "type": "number" } }, "required": [ "kind", "volume_sats", "sales" ] } }, "top_sales": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string" }, "ref_id": { "type": "string" }, "asset": { "type": "string" }, "asset_longname": { "type": [ "string", "null" ] }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "buyer": { "type": "string" }, "seller": { "type": "string" }, "broadcast_at": { "type": "number" } }, "required": [ "txid", "ref_id", "asset", "price_sats", "buyer", "seller", "broadcast_at" ] } } }, "required": [ "as_of", "since", "market", "sales", "daily", "depth", "sale_types", "top_sales" ], "description": "Public market snapshot. Sales are confirmed, non-dropped fills in the trailing 30 days; open offers count unique funding slots, not alternatives.", "x-generated-wire-type": "MarketAnalytics" }, "WireMediaKind": { "type": "string", "enum": [ "image", "animation", "video", "html", "svg" ], "description": "What an asset's stored art is, as the CDN serves it: the card derivative presents `image` and `animation`; `video` wants a player; `html` is an on-chain page for a sandboxed frame; `svg` is crisp at any size.", "x-generated-wire-type": "MediaKind" }, "WireOfferAcceptanceSelectionResult": { "type": "object", "properties": { "offer_count": { "type": "number" }, "funding_slot_count": { "type": "number" }, "settlement_count": { "type": "number" }, "reserves_funding": { "type": "boolean", "const": false }, "selections": { "type": "array", "items": { "type": "object", "properties": { "offer_id": { "type": "string" }, "funding_slot_id": { "type": "string" }, "bid": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "mode": { "type": "string", "enum": [ "interactive", "presigned" ] } }, "required": [ "offer_id", "funding_slot_id", "bid", "price_sats", "mode" ] } } }, "required": [ "offer_count", "funding_slot_count", "settlement_count", "reserves_funding", "selections" ], "x-generated-wire-type": "OfferAcceptanceSelectionResult" }, "WireOfferCancelResult": { "type": "object", "properties": { "cancelled": { "type": "boolean", "const": true } }, "required": [ "cancelled" ], "x-generated-wire-type": "OfferCancelResult" }, "WireOfferCoverageSummary": { "type": "object", "properties": { "offer_id": { "type": "string" }, "uncovered": { "type": "number" }, "more": { "type": "boolean" } }, "required": [ "offer_id", "uncovered", "more" ], "description": "One live offer whose policy matches listings its funding slot has not authorized yet. `uncovered` is capped at one wallet prompt's worth; `more` says the cap was reached. Offers with nothing uncovered are omitted.", "x-generated-wire-type": "OfferCoverageSummary" }, "WireOfferPlacementCancelResult": { "type": "object", "properties": { "placement_id": { "type": "string" }, "cancelled_offers": { "type": "integer", "minimum": 0 } }, "required": [ "placement_id", "cancelled_offers" ], "x-generated-wire-type": "OfferPlacementCancelResult" }, "WireOfferPlacementResult": { "type": "object", "properties": { "placement_id": { "type": "string" }, "slot_count": { "type": "number" }, "target_count": { "type": "number" }, "offer_count": { "type": "number" }, "bidder": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "funding_slots": { "type": "array", "items": { "type": "object", "properties": { "funding_slot_id": { "type": "string" }, "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "funding_slot_id", "txid", "vout" ] } }, "offer_ids": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/WireOfferTargetInput" } }, "expires_at": { "type": "number" }, "delivery": { "type": "object", "properties": { "mode": { "$ref": "#/components/schemas/WireDeliveryMode" }, "address": { "type": "string" }, "utxo_value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "mode", "address" ] } }, "required": [ "placement_id", "slot_count", "target_count", "offer_count", "bidder", "price_sats", "platform_fee_sats", "funding_slots", "offer_ids", "targets", "expires_at", "delivery" ], "x-generated-wire-type": "OfferPlacementResult" }, "WireOfferSlotReleaseResult": { "type": "object", "properties": { "bidder": { "type": "string" }, "slots": { "type": "array", "items": { "type": "object", "properties": { "funding_slot_id": { "type": "string" }, "txid": { "type": "string" }, "vout": { "type": "number" }, "value_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "live_offers": { "type": "number", "description": "Live offers this slot still backs; 0 for an ended slot." } }, "required": [ "funding_slot_id", "txid", "vout", "value_sats", "live_offers" ] }, "description": "The slots in the PSBT's input order, with their chain values." }, "psbt_hex": { "type": "string" }, "expected_txid": { "type": "string" }, "fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "output_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "fee_rate": { "type": "number" }, "signing": { "type": "object", "properties": { "signer_address": { "type": "string" }, "inputs_to_sign": { "type": "array", "items": { "type": "number" } }, "sighash": { "type": "string", "enum": [ "DEFAULT", "ALL" ] } }, "required": [ "signer_address", "inputs_to_sign", "sighash" ] } }, "required": [ "bidder", "slots", "psbt_hex", "expected_txid", "fee_sats", "output_sats", "fee_rate", "signing" ], "description": "An unsigned self-send of one or more of the bidder's exact-offer bid slots back to the bidder's own script: the certain, on-chain cancel for `exact_offer_v1` (spending a slot retires every offer and authorization on it). Composed from chain facts, never stored; the wallet side proves the PSBT spends exactly `slots` into one output before signing.", "x-generated-wire-type": "OfferSlotReleaseResult" }, "WireOfferTargetInput": { "type": "object", "properties": { "target_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] }, "scope": { "type": "string", "enum": [ "asset", "collection" ] }, "asset": { "type": [ "string", "null" ] }, "collection": { "type": [ "string", "null" ] }, "max_supply_units": { "type": [ "number", "null" ] }, "min_supply_units": { "type": [ "number", "null" ] }, "issued_year": { "type": [ "number", "null" ] }, "series": { "type": [ "number", "null" ] }, "artist": { "type": [ "string", "null" ] } }, "required": [ "scope" ], "x-generated-wire-type": "OfferTargetInput" }, "WirePolicyAcceptResult": { "type": "object", "properties": { "protocol_version": { "type": "string", "const": "funded_policy_offer_v1" }, "accept_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/WirePolicyAcceptStatus" }, "parent_txid": { "type": "string" }, "child_txid": { "type": "string" }, "asset": { "type": "string" }, "seller": { "type": "string" }, "asset_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "refusal_code": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "settlement": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" }, "attempts": { "type": "number" }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "status", "attempts", "last_error" ] }, { "type": "null" } ] }, "created_at": { "type": "number" }, "updated_at": { "type": "number" }, "already_completed": { "type": "boolean" } }, "required": [ "protocol_version", "accept_id", "status", "parent_txid", "child_txid", "asset", "seller", "asset_outpoint", "price_sats", "platform_fee_sats", "network_fee_sats", "seller_proceeds_sats", "refusal_code", "last_error", "settlement", "created_at", "updated_at" ], "x-generated-wire-type": "PolicyAcceptResult" }, "WirePolicyAcceptStatus": { "type": "string", "enum": [ "quoted", "signed", "journaled", "broadcast", "confirmed", "conflicted", "failed" ], "x-generated-wire-type": "PolicyAcceptStatus" }, "WirePolicyFundingStatus": { "type": "string", "enum": [ "active", "claimed", "settled", "spent_external", "cancelled", "swept", "onchain_funded", "invalid" ], "x-generated-wire-type": "PolicyFundingStatus" }, "WirePolicyOfferCancellationResult": { "type": "object", "properties": { "parent_txid": { "type": "string" }, "cancelled": { "type": "boolean", "const": true }, "recorded_at": { "type": "number", "description": "Signer clock of the first recorded cancellation." }, "funding_cancelled": { "type": "boolean", "description": "True once every alternative of the funding set is cancelled; its anchor is then swept with the next batch." }, "already_signed": { "type": "boolean", "description": "An acceptance signature was already released for this parent: only a hard cancel (spending a funding input) can still stop it." }, "bitcoin_invalidation": { "type": "object", "properties": { "type": { "type": "string", "const": "spend_funding_input" }, "outpoints": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] } } }, "required": [ "type", "outpoints" ] } }, "required": [ "parent_txid", "cancelled", "recorded_at", "funding_cancelled", "already_signed", "bitcoin_invalidation" ], "x-generated-wire-type": "PolicyOfferCancellationResult" }, "WirePolicyOfferHardCancelResult": { "type": "object", "properties": { "parent_txid": { "type": "string" }, "funding_id": { "type": "string" }, "funding_inputs": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" }, "value_sats": { "$ref": "#/components/schemas/WireSatoshis" } }, "required": [ "txid", "vout", "value_sats" ] }, "description": "The funding set's still-unspent inputs, in the PSBT's input order: the wallet side proves the PSBT spends exactly these." }, "psbt_hex": { "type": "string" }, "expected_txid": { "type": "string" }, "fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "output_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "fee_rate": { "type": "number" }, "signing": { "type": "object", "properties": { "signer_address": { "type": "string" }, "inputs_to_sign": { "type": "array", "items": { "type": "number" } }, "sighash": { "type": "string", "enum": [ "DEFAULT", "ALL" ] } }, "required": [ "signer_address", "inputs_to_sign", "sighash" ] } }, "required": [ "parent_txid", "funding_id", "funding_inputs", "psbt_hex", "expected_txid", "fee_sats", "output_sats", "fee_rate", "signing" ], "x-generated-wire-type": "PolicyOfferHardCancelResult" }, "WirePolicyOfferKind": { "type": "string", "enum": [ "asset", "collection", "trait" ], "description": "`trait` = a collection policy with at least one trait predicate.", "x-generated-wire-type": "PolicyOfferKind" }, "WirePolicyOfferNetEstimate": { "type": "object", "properties": { "fee_rate": { "type": "number" }, "child_vsize": { "type": "number" }, "package_vsize": { "type": "number" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "seller_net_sats": { "$ref": "#/components/schemas/WireSignedSatoshis" }, "acceptable": { "type": "boolean", "description": "False when the net falls at or below dust at this rate (grey it out)." } }, "required": [ "fee_rate", "child_vsize", "package_vsize", "network_fee_sats", "platform_fee_sats", "seller_net_sats", "acceptable" ], "description": "What accepting would pay a seller at `fee_rate`, from the offer's real parent size and a P2TR seller/fee child estimate. A quote, not a promise: the accept preflight recomputes from the seller's actual UTXO.", "x-generated-wire-type": "PolicyOfferNetEstimate" }, "WirePolicyOfferPlacementResult": { "type": "object", "properties": { "protocol_version": { "type": "string", "const": "funded_policy_offer_v1" }, "funding_id": { "type": "string" }, "funding_slot_id": { "type": "string" }, "already_placed": { "type": "boolean" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/WireBidderPolicyOffer" } } }, "required": [ "protocol_version", "funding_id", "funding_slot_id", "already_placed", "offers" ], "x-generated-wire-type": "PolicyOfferPlacementResult" }, "WirePreparedAssetOutpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" } }, "required": [ "txid", "vout", "quantity_raw" ], "description": "One exact one-unit attached outpoint eligible for a listing authorization.", "x-generated-wire-type": "PreparedAssetOutpoint" }, "WirePreparedAssetResult": { "type": "object", "properties": { "asset": { "type": "string" }, "asset_longname": { "type": [ "string", "null" ] }, "collection": { "type": "string" }, "divisible": { "type": "number" }, "protocol_subtype": { "type": [ "string", "null" ], "description": "Global Bitcoin Stamps subtype, independent of collection membership." }, "media_kind": { "anyOf": [ { "$ref": "#/components/schemas/WireMediaKind" }, { "type": "null" } ], "description": "Indexed media behavior used by every inventory presentation." }, "prepared_units": { "type": "number" }, "outpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WirePreparedAssetOutpoint" } }, "floor_sats": { "anyOf": [ { "$ref": "#/components/schemas/WireSatoshis" }, { "type": "null" } ], "description": "The asset's market at read time, so a seller can price against it: the public floor and listed depth, and the best standing offer." }, "listed": { "type": "number" }, "best_offer_sats": { "anyOf": [ { "$ref": "#/components/schemas/WireSatoshis" }, { "type": "null" } ] } }, "required": [ "asset", "asset_longname", "best_offer_sats", "collection", "divisible", "floor_sats", "listed", "media_kind", "outpoints", "prepared_units", "protocol_subtype" ], "description": "Attached inventory that can be priced without another attach transaction.", "x-generated-wire-type": "PreparedAssetResult" }, "WirePresignedAuthorizationValidity": { "type": "object", "properties": { "marketplace_expires_at": { "type": "number" }, "bitcoin_expires_at": { "type": "null" }, "bitcoin_invalidation": { "type": "object", "properties": { "type": { "type": "string", "const": "spend_funding_outpoint" }, "outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] } }, "required": [ "type", "outpoint" ] } }, "required": [ "marketplace_expires_at", "bitcoin_expires_at", "bitcoin_invalidation" ], "x-generated-wire-type": "PresignedAuthorizationValidity" }, "WirePublicListing": { "type": "object", "properties": { "id": { "type": "string" }, "asset": { "type": "string" }, "asset_longname": { "type": [ "string", "null" ], "description": "Present on discovery feeds that already join indexed asset metadata." }, "seller": { "type": "string" }, "utxo_txid": { "type": "string" }, "utxo_vout": { "type": "number" }, "quantity_raw": { "$ref": "#/components/schemas/WireRawQuantity" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "created_at": { "type": "number" }, "protocol_subtype": { "type": [ "string", "null" ], "description": "Present on discovery/storefront feeds, where tile shape is needed. Book reads may omit it because the surrounding asset already supplies it." }, "media_kind": { "anyOf": [ { "$ref": "#/components/schemas/WireMediaKind" }, { "type": "null" } ], "description": "Present on discovery feeds that render asset media cards." } }, "required": [ "id", "asset", "seller", "utxo_txid", "utxo_vout", "quantity_raw", "price_sats", "created_at" ], "x-generated-wire-type": "PublicListing" }, "WireRawQuantity": { "type": "string", "description": "Counterparty atomic units. A string preserves integers beyond JSON's safe numeric range; divisibility affects display, never this wire value.", "pattern": "^[0-9]+$", "x-generated-wire-type": "RawQuantity" }, "WireSatoshis": { "type": "integer", "description": "Integer satoshis, exactly representable as a JSON number. Aggregated historical volume can exceed Bitcoin's supply, so this is the safe JSON integer ceiling, not a single-transaction spending limit.", "minimum": 0, "maximum": 9007199254740991, "x-generated-wire-type": "Satoshis" }, "WireSellerExactAcceptance": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "offer_id": { "type": "string" }, "asset": { "type": "string" }, "target_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "state": { "$ref": "#/components/schemas/WireSellerExactAcceptanceState" }, "txid": { "type": [ "string", "null" ] }, "created_at": { "type": "number" }, "updated_at": { "type": "number" } }, "required": [ "authorization_id", "offer_id", "asset", "target_outpoint", "price_sats", "seller_proceeds_sats", "state", "txid", "created_at", "updated_at" ], "x-generated-wire-type": "SellerExactAcceptance" }, "WireSellerExactAcceptanceState": { "type": "string", "enum": [ "claiming", "prepared", "broadcast", "conflicted", "dropped" ], "description": "One of the seller's acceptances the server still owns, from `GET /address/{seller}/exact-acceptances`. `claiming`: the seller's signature won the funding claim but no bytes are journaled yet. `prepared`: exact bytes are journaled and being relayed. `broadcast`: the network has them; waiting for confirmation. `conflicted`/`dropped`: a real loss, shown for a day. Confirmed acceptances leave the set.", "x-generated-wire-type": "SellerExactAcceptanceState" }, "WireSellerExactOfferSummary": { "type": "object", "properties": { "authorization_id": { "type": "string" }, "offer_id": { "type": "string" }, "funding_slot_id": { "type": "string" }, "asset": { "type": "string" }, "bidder": { "type": "string" }, "seller": { "type": "string" }, "price_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "seller_proceeds_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "network_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "platform_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "prefunded_fee_sats": { "$ref": "#/components/schemas/WireSatoshis" }, "fee_rate": { "type": "number" }, "expires_at": { "type": "number" }, "requires_buyer_action": { "type": "boolean", "const": false }, "target_outpoint": { "type": "object", "properties": { "txid": { "type": "string" }, "vout": { "type": "number" } }, "required": [ "txid", "vout" ] }, "offer_scope": { "type": "string", "enum": [ "asset", "collection" ], "description": "The authorized offer's scope: `asset` is an individual bid (the kind a holdings view offers to counter), `collection` a collection/trait policy." }, "created_at": { "type": "number" } }, "required": [ "asset", "authorization_id", "bidder", "created_at", "expires_at", "fee_rate", "funding_slot_id", "network_fee_sats", "offer_id", "offer_scope", "platform_fee_sats", "prefunded_fee_sats", "price_sats", "requires_buyer_action", "seller", "seller_proceeds_sats", "target_outpoint" ], "x-generated-wire-type": "SellerExactOfferSummary" }, "WireSettlementStatus": { "type": "string", "enum": [ "prepared", "broadcast", "confirmed", "conflicted", "dropped" ], "x-generated-wire-type": "SettlementStatus" }, "WireSignedSatoshis": { "type": "integer", "description": "A projected net can be negative when fees exceed the offered proceeds.", "minimum": -9007199254740991, "maximum": 9007199254740991, "x-generated-wire-type": "SignedSatoshis" }, "WireSigningInstruction": { "type": "object", "properties": { "psbt_hex": { "type": "string" }, "inputs_to_sign": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "string", "const": "all" } ] }, "signer_address": { "type": "string" }, "sighash": { "$ref": "#/components/schemas/WireSigningSighash" }, "expected_txid": { "type": "string" } }, "required": [ "inputs_to_sign" ], "x-generated-wire-type": "SigningInstruction" }, "WireSigningSighash": { "type": "string", "enum": [ "ALL", "DEFAULT|ALL", "SINGLE|ANYONECANPAY" ], "x-generated-wire-type": "SigningSighash" } } } }