# Markets, trading, and liquidity

Use marketplace and exchange approvals when the transaction exchanges assets or settles an order. A posted order, a filled order, and a direct payment are distinct states.

## Auctions

`bb build auction` creates an `Auction` collection with one auction token. Configure `--seller`, `--bid-deadline` (default `7d`), and `--accept-window` (default `7d` after the bid deadline), plus collection metadata. The seller defaults to the creator.

The seller's mint-to-winner approval operates during the acceptance window, permits one successful transfer, and does not bypass the winning bidder's incoming payment approval. A separate burn approval permits holder burning. The winner is accepted by the seller; the template does not automatically select the highest displayed bid or run a settlement timer.

Discover and inspect through `bb auctions list`, `bb auctions show <collection-id>`, and `bb auctions status <collection-id>`. The actions are `bb auctions place-bid`, `cancel-bid`, and `accept-bid`; use each command's `--help` for its bidder, approval ID, and payment options. A bid is authorization, not proof of payment or reserved funds. Acceptance requires a still-valid bid, sufficient funds, the seller's authorization, and the actual inclusive transfer-time window.

## NFT marketplace and generic intents

`NFTMarketplace` (validator alias `Tradable`) adds the collection transfer capability needed for user listings and bids. It does not create an NFT collection on its own.

| Surface | Registered commands | Purpose |
| --- | --- | --- |
| Approval construction | `bb build listing`, `bb build bid` | Build user-side sale and purchase approvals |
| Marketplace actions | `bb nfts bid`, `list`, `cancel`, `buy`, `sell` | Create, remove, or execute marketplace orders |
| Marketplace reads | `bb nfts orders`, `history` | Inspect open orders and historical activity |
| Generic OTC intents | `bb build intent`, `bb intents create`, `list`, `show`, `fill`, `cancel` | Exchange through configured user approvals |

Here `bb nfts list` creates a listing; it is not a generic collection-browsing command. An intent cancellation removes the relevant authorization after the update executes; it cannot undo a previously committed fill. Track the exact user, approval level, approval ID, and fill trackers, then inspect final balances. Do not combine different approvals solely by a shared tracker label.

## Binary prediction markets

`bb build prediction-market --resolver <address> --denom USDC` creates a `Prediction Market` collection; `--verifier` is the resolver flag's alias. Provide collection metadata and the creator as with other builders. The existing presets cover paired minting, transferability, pre-settlement paired redemption, YES/NO resolution, and outcome payout paths.

| Phase | Commands | Meaning |
| --- | --- | --- |
| Inspect | `bb prediction-markets list`, `show`, `status` | Read market configuration and state |
| Back and redeem pairs | `bb prediction-markets deposit`, `redeem` | Mint or redeem the paired position using the recognized approval paths |
| Trade one side | `bb prediction-markets buy-yes`, `buy-no`, `sell-yes`, `sell-no` | Construct orders/actions for a side; inspect each command's help and output |
| Cancel an order | `bb prediction-markets cancel` | Remove order authorization |
| Resolve | `bb prediction-markets resolve` | Resolver-authorized outcome action |
| Build side intents | `bb build pm-buy-intent`, `bb build pm-sell-intent` | Construct the corresponding user approval |

The resolver is a trust assumption, not a decentralized oracle supplied by this template. Before settlement, paired redemption differs from selling one side to another trader. Resolution and payout execution are separate facts: inspect outcome authorization, held positions, escrow, and executed transfers. An order's quote is not a guaranteed execution price or available liquidity.

## Liquidity Pools

`Liquidity Pools` is a collection capability used with the chain DEX. `bb build smart-token --tradable` adds it to that Smart Token variant. The CLI exposes `bb pools`, `bb swap`, and `bb pairs`; inspect their subcommand help for pool creation, liquidity, quotes, and pair discovery. There is no `bb build liquidity-pool` collection builder.

A capability tag does not create a pool, seed reserves, or guarantee liquidity. Check collection invariants, eligible wrapper denominations, actual pool reserves, and transaction limits. Market price discovery and swap execution are separate from an invoice's fixed-denomination payment terms.

See [auction primitives](https://docs.bitbadges.io/agents/skills/auction), [tradable approvals](https://docs.bitbadges.io/agents/skills/tradable), [prediction market primitives](https://docs.bitbadges.io/agents/skills/prediction-market), [liquidity pool primitives](https://docs.bitbadges.io/agents/skills/liquidity-pools), and [approval trackers](https://docs.bitbadges.io/token-standard/approval-criteria/approval-trackers).

## Auction JSON

Save the following input as `auction.json`, replace the demo addresses and metadata, then build it with the CLI command below. `seller` authorizes acceptance. `bidDeadline` is a duration from construction; `acceptWindow` starts at that resolved deadline. Bids, bidder funds, winning-bid selection, and settlement are separate state. This input does not assert an automatic highest-bid oracle.

<!-- sdk-example: buildAuction -->
```json
{
  "seller": "bb1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zql3w7",
  "bidDeadline": "7d",
  "acceptWindow": "7d",
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build auction --json auction.json \
  --creator "$CREATOR" --output-file auction-proposal.json
```

Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildAuction`.

## Prediction JSON

Save the following input as `prediction-market.json`, replace the demo addresses and metadata, then build it with the CLI command below. `verifier` identifies the resolver; `denom` is the collateral coin. Resolution evidence and redemption transactions are separate from collection creation. The binary outcome token IDs and approval paths are generated by the builder.

<!-- sdk-example: buildPredictionMarket -->
```json
{
  "verifier": "bb1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zql3w7",
  "denom": "BADGE",
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build prediction-market --json prediction-market.json \
  --creator "$CREATOR" --output-file prediction-market-proposal.json
```

Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildPredictionMarket`.

## Listing JSON

Save the following input as `listing.json`, replace the demo addresses and metadata, then build it with the CLI command below. This builds an outgoing order approval on an **existing** compatible collection, not a new NFT collection. `address` is the seller; `tokenIds` selects one ID; `price` is in display units. Replace collection `46`; successful construction does not prove ownership or collection permission.

<!-- sdk-example: buildListing -->
```json
{
  "address": "bb1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zql3w7",
  "collectionId": "46",
  "tokenIds": "1",
  "price": 5,
  "denom": "BADGE",
  "maxSales": 1,
  "expiration": "30d"
}
```

```bash
bb build listing --json listing.json \
  --address "$(jq -r '.address' listing.json)" \
  --collection-id "$(jq -r '.collectionId' listing.json)" \
  --token-ids "$(jq -r '.tokenIds' listing.json)" \
  --price "$(jq -r '.price' listing.json)" \
  --denom "$(jq -r '.denom' listing.json)" \
  --creator "$CREATOR" --output-file listing-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildListing`.

## Display Currency

The NFT creation form can add `NFTPricingDenom:<denom>` to choose a pricing display denomination. The standards selector also recognizes the older `DefaultDisplayCurrency:<denom>` form when replacing that preference. These are UI hints, not additional payment alternatives or enforced settlement terms:

```json
{
  "standards": ["NFTs", "NFTMarketplace", "NFTPricingDenom:ubadge"]
}
```

This is a standards-field fragment. The actual listing or bid approval sets the required coin denomination and amount. Always review that approval; a displayed symbol or conversion does not authorize payment in another currency.