Marketplace v1

The Marketplace v1 service is a durable protocol authority backed by Atomicals ElectrumX, Bitcoin Core, and the token-explorer database. It does not infer ownership from an address string or from indexer metadata alone.

Marketplace authority flow. A seller proves control of their address with a BIP-322 proof, which moves nothing, and receives a short lived owner session. The prepare step verifies the collateral against Bitcoin Core and the Atomicals provider under one stable checkpoint, and returns exactly what the wallet must sign. The seller signs with a scope that binds their payout output. A buyer reserves the listing, the purchase is prepared deterministically, the buyer signs, and the signed material is validated with Atomicals dry validation and a Bitcoin Core mempool acceptance test before anything is broadcast. Failing at any point before broadcast costs nothing.

Marketplace authority flow

A seller proves control of their address with a BIP-322 proof, which moves nothing, and receives a short lived owner session. The prepare step verifies the collateral against Bitcoin Core and the Atomicals provider under one stable checkpoint, and returns exactly what the wallet must sign. The seller signs with a scope that binds their payout output. A buyer reserves the listing, the purchase is prepared deterministically, the buyer signs, and the signed material is validated with Atomicals dry validation and a Bitcoin Core mempool acceptance test before anything is broadcast. Failing at any point before broadcast costs nothing.

Four isolated lanes

One router exposes four protocol authorities: arc20, atomicals_nft, realms, and subrealms. They share the durable transaction engine and operational credentials, but every route, cursor, idempotency scope, listing, offer, order, reservation, browse query, and status count is protocol scoped. Non-ARC-20 storage keys are prefixed internally, and the prefix is never returned as a public asset ID.

Lane	Collateral	Extra check
arc20	The verified ticker winner, trading the complete FT value	None beyond the shared set
atomicals_nft	An authoritative compact Atomical ID	Rejects realm, subrealm, FT, container, and item subtypes
realms	A Realm	Resolves the verified name winner before every mutation
subrealms	A Subrealm	Resolves the verified name winner before every mutation

The three non-fungible lanes always expose quantityAtomic as 1.

Safety model

Everything is off by default

All marketplace and action gates default to false. Enabling an action gate while the marketplace gate is false is a configuration error. Enabling also requires separate request-HMAC, internal execution-bearer, internal execution-HMAC, and Bitcoin Core credentials, and the two HMAC secrets must be distinct. Buy or offer execution additionally requires an exact fee script. Enabling requires a release SHA identifying the exact deployed indexer commit.

Every internal readiness response binds that revision and the exact index-atomicals-{protocolId}-settlement-v1 authority identity, so a stale binary or a confused settlement authority is rejected before wallet preparation.

What must agree before collateral is accepted

For ARC-20, all of these independent views must agree:

1. The ticker resolves to its verified authoritative FT winner.
2. Bitcoin Core reports a confirmed, live UTXO with the exact value and owner script, and a mature coinbase where applicable.
3. blockchain.atomicals.at_location reports exactly that location, script, value, and one authoritative FT.
4. blockchain.atomicals.listscripthash reports exactly one active row whose coloured balance is the full UTXO value.
5. Bitcoin height and hash, and the Atomicals Bitcoin and Atomicals tips, remain unchanged across the verification bracket.

Buyer funding inputs must be confirmed P2WPKH or key-path P2TR outputs, uncoloured in both the active script hash view and location history. The Atomicals transaction blueprint must assign the selected inputs cleanly to output zero, with no operation, no NFT, no mixed Atomical ID, and no burn.

Always rejected

Mixed collateral, spent outputs, checkpoint drift, ambiguous balances, Atomicals operations inside the settlement transaction, burns, output assignments that do not move the exact selected Atomical, wallet supplied mutations to a stored reservation projection, and unsupported adapter filters.

Routes

Public

Generated from docs/arc20-marketplace-v1.rst in Universe ARC-20 index and Marketplace v1 authority at 670030e50071. 22 routes. CI fails when this inventory and the OpenAPI document disagree in either direction.

Public route inventory for Atomicals Marketplace v1 authority

Method	Path	Auth	Summary
GET	/api/marketplace/v1/protocols/{protocolId}	bearer	Machine readable route and signing contract
GET	/api/marketplace/v1/protocols/{protocolId}/status	bearer	Non-probing status view
GET	/api/marketplace/v1/protocols/{protocolId}/readiness	bearer	Bitcoin Core and Atomicals checkpoint probe
GET	/api/marketplace/v1/protocols/{protocolId}/listings	bearer	List listings
GET	/api/marketplace/v1/protocols/{protocolId}/listings/{listingId}	bearer	Read one listing
POST	/api/marketplace/v1/protocols/{protocolId}/auth/challenges	bearer and signature	Request an ownership challenge
POST	/api/marketplace/v1/protocols/{protocolId}/auth/challenges/{challengeId}/verify	bearer and signature	Verify a BIP-322 simple proof and issue an owner session
POST	/api/marketplace/v1/protocols/{protocolId}/listings/prepare	bearer, signature, owner session	Prepare a listing
POST	/api/marketplace/v1/protocols/{protocolId}/listings/finalize	bearer, signature, owner session	Finalise a signed listing
POST	/api/marketplace/v1/protocols/{protocolId}/listings/{listingId}/update/prepare	bearer, signature, owner session	Prepare a listing update
POST	/api/marketplace/v1/protocols/{protocolId}/listings/{listingId}/update/finalize	bearer, signature, owner session	Finalise a signed listing update
POST	/api/marketplace/v1/protocols/{protocolId}/listings/{listingId}/delist	bearer, signature, owner session	Delist
POST	/api/marketplace/v1/protocols/{protocolId}/reservations	bearer and signature	Reserve a listing for purchase
GET	/api/marketplace/v1/protocols/{protocolId}/reservations/{reservationId}	bearer	Reload a reservation without mutation
POST	/api/marketplace/v1/protocols/{protocolId}/purchases/prepare	bearer and signature	Prepare the settlement transaction
POST	/api/marketplace/v1/protocols/{protocolId}/purchases/{orderId}/validate-signed	bearer and signature	Validate signed material before broadcast
POST	/api/marketplace/v1/protocols/{protocolId}/purchases/{orderId}/broadcast	bearer and signature	Broadcast after validation passes
POST	/api/marketplace/v1/protocols/{protocolId}/offers	bearer and signature	Create an offer
POST	/api/marketplace/v1/protocols/{protocolId}/offers/{offerId}/cancel	bearer, signature, owner session	Cancel an offer
POST	/api/marketplace/v1/protocols/{protocolId}/offers/{offerId}/accept	bearer, signature, owner session	Accept an offer
GET	/api/marketplace/v1/protocols/{protocolId}/settlements/{orderId}	bearer	Read settlement state
POST	/api/marketplace/v1/protocols/{protocolId}/buys deprecated Use /reservations and /purchases	bearer and signature	Legacy alias

Adapter

Direct, envelope free pages at /v1/marketplace/protocols/{protocolId}. Pages have exactly {items, nextCursor?} and accept the cursor, limit, assetId, collectionId, owner, status, sort, and direction query fields. Unsupported filters fail closed, and ARC-20 collection pages are empty by design. Listing and offer IDs exposed by this bridge are stable lowercase UUIDs reversibly mapped to the authority’s prefixed storage keys.

Generated from docs/arc20-marketplace-v1.rst in Universe ARC-20 index and Marketplace v1 authority at 670030e50071. 8 routes. CI fails when this inventory and the OpenAPI document disagree in either direction.

Public route inventory for Atomicals Marketplace v1 authority

Method	Path	Auth	Summary
GET	/v1/marketplace/protocols/{protocolId}/assets	bearer	Envelope free adapter page
GET	/v1/marketplace/protocols/{protocolId}/listings	bearer	Envelope free adapter page
GET	/v1/marketplace/protocols/{protocolId}/listings/{listingId}	bearer	Envelope free adapter read
GET	/v1/marketplace/protocols/{protocolId}/offers	bearer	Envelope free adapter page
GET	/v1/marketplace/protocols/{protocolId}/collections	bearer	Envelope free adapter page. ARC-20 collection pages are empty
GET	/v1/marketplace/protocols/{protocolId}/activity	bearer	Envelope free adapter page
GET	/v1/marketplace/protocols/{protocolId}/position-source/ready	bearer	Composite position source readiness
GET	/v1/marketplace/protocols/{protocolId}/position-source/outpoints/{txid}:{vout}	bearer	Composite position evidence for an outpoint

Operator

Generated from docs/arc20-marketplace-v1.rst in Universe ARC-20 index and Marketplace v1 authority at 670030e50071. 2 routes. CI fails when this inventory and the OpenAPI document disagree in either direction.

Public route inventory for Atomicals Marketplace v1 authority

Method	Path	Auth	Summary
POST	/api/marketplace/v1/protocols/{protocolId}/settlements/{orderId}/reconcile	bearer, signature, operator	Operator reconciliation against chain evidence
POST	/api/marketplace/v1/protocols/{protocolId}/orders/{orderId}/reconcile deprecated Use /settlements/{orderId}/reconcile	bearer, signature, operator	Legacy alias

Internal bridge

Not publicly reachable. Documented so integrators understand where the boundary sits.

Generated from docs/arc20-marketplace-v1.rst in Universe ARC-20 index and Marketplace v1 authority at 670030e50071. 3 routes. CI fails when this inventory and the OpenAPI document disagree in either direction.

Public route inventory for Atomicals Marketplace v1 authority

Method	Path	Auth	Summary
GET	/v1/marketplace/protocols/{protocolId}/internal/readiness	internal bridge only	Trusted bridge readiness probe. Not publicly reachable
POST	/v1/marketplace/protocols/{protocolId}/internal/actions	internal bridge only	Trusted bridge action dispatcher. Not publicly reachable
GET	/v1/marketplace/protocols/{protocolId}/internal/reservations/{reservationId}	internal bridge only	Trusted bridge reservation reload. Not publicly reachable

Authentication and signing

Reads use a bearer token. Public mutations add a replay-resistant signature:

v1\n{timestamp}\n{nonce}\n{method}\n{path}\n{sha256(exact_body_bytes)}

Headers: X-Marketplace-Key-Id: universe-marketplace-v1, X-Marketplace-Timestamp, X-Marketplace-Nonce, X-Marketplace-Signature. Mutations require Idempotency-Key.

Owner actions use a short lived X-Marketplace-Owner-Authorization session, issued only after a BIP-322 simple proof with message type smp, for P2WPKH or key-path P2TR.

The internal bridge requires three independent credentials and its own signature over {timestamp}\n{method}\n{path}\n{sha256(exact_body_bytes)}, with a sixty second acceptance window. The signed path is the exact protocol-specific request path, so a signature for another protocol path is rejected.

No credential value appears anywhere in this documentation. See authentication.

The PSBT and signing contract

Seller preparation. PSBT v0, one collateral input, one payout output, sequence 0xfffffffd, witness UTXO, and sighash type 0x83, which is SIGHASH_SINGLE with ANYONECANPAY. The authority verifies the signature before persisting a live listing.

Purchase preparation is deterministic:

Position	Contents
Input 0	The first buyer funding input
Inputs 1 to N	Seller inputs in request order
Remaining inputs	The remaining buyer funding inputs
Output 0	The complete asset amount
Outputs 1 to N	The corresponding seller payouts
Next output	The marketplace fee output, when non-zero
Last output	Buyer change, when it is not dust

Every seller input retains sighash 0x83 after combination. Buyer P2WPKH inputs require SIGHASH_ALL; key-path P2TR inputs allow default or ALL.

The signed PSBT must preserve the prepared unsigned digest, the exact previous outputs, the output ordering, the miner fee, the fee-rate ceiling, and the Atomicals transfer blueprint. The authority performs Atomicals dry validation and Bitcoin Core testmempoolaccept before writing a durable broadcast intent.

Ambiguous outcomes are never resolved by guessing

A transport failure after a durable broadcast intent is an ambiguous outcome and never triggers a blind rebroadcast. Reconciliation resolves it against chain evidence.

Reservations

A reservation request carries 1 through 63 buyer inputs, leaving one of the maximum 64 ordered spend claims for collateral.

The reservation response is the complete projection: authoritative UUID reservation, subject, action-intent, claim, and spend-fence identifiers; exactly one non-null listingId or offerId; trusted actor and request context; ordered fees and spend claims; and every fee, payout, protocol-data, spend-claim, and economic commitment hash.

The economic hash uses the exact bitcoin-universe:marketplace-v1:purchase-reservation-economics:v1 schema and commits an absent optional requestId as JSON null. Reload and purchase preparation both recompute and compare the entire stored projection. Wallet supplied mutations are rejected.

Exact protocol data

Action	Accepted shape
Listing validation	{location, payoutAddress?}
Update	{payoutAddress?}
Delist and offer cancellation	{}
Offer creation	{listingId, expectedListingRevision}
Purchase reservation	{buyerInputs, receiveAddress, changeAddress?, feeRateAtomicVb}

Anything else is rejected. These shapes are exact, not minimums.

Amounts

Every amount is a decimal string. JSON numbers are rejected for satoshi and protocol quantities. ARC-20 listings and offers cover the complete coloured UTXO. Non-fungible listings have quantity one and their price is the exact total Bitcoin consideration.

Order lifecycle

Orders move through prepared, finalized, broadcasting, submitted or mempool, and confirmed, or an explicit failure or recovery state. Reconciliation compares Bitcoin Core transaction, mempool, block-header, spending-prevout, and UTXO evidence. Listings settle only after the configured confirmation depth. Replacement, drop, conflict, and reorganisation evidence is recorded rather than guessed.

Partial unique indexes enforce one live listing per collateral location, one open buyer offer per listing, and one active reservation per listing. Every mutation uses an expected revision inside a single immediate transaction.

Composite position source

position-source routes join Bitcoin Core’s current UTXO, the Atomicals location inventory, active script hash balances, the ticker winner, and Realm and Subrealm winners between stable checkpoint probes. Responses use universe-marketplace-protocol-position-v1 and contain only positions from that protocol.

ARC-20 returns the exact coloured atomic quantity; non-fungible positions are singletons. Spent and unrelated outputs return a complete empty set. Mixed, unknown, non-standard, or internally inconsistent Atomicals fail closed rather than disappearing from composite evidence.

Deprecated aliases

Deprecated	Replacement
POST /buys	POST /reservations then POST /purchases/prepare
POST /orders/{orderId}/reconcile	POST /settlements/{orderId}/reconcile

See versioning and deprecation.