Servers Playground How we check Add a server Log in

SpellBook Finance

Working · 1.7 s

com.spellbook-finance/mcpv1.0.0 Domain verified

Magic: The Gathering card prices, movers, arbitrage, sealed box EV, and seller inventory tools.

Entertainment & Games

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://api.spellbook-finance.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

spellbook_agent_gap_report

After finishing the task, ask the person whether they consent to send one bounded capability-gap report to SpellBook. Call this tool only after an explicit yes for this report and set consentToShare to true. Use it when a needed field was null, you guessed a number because no tool supplied it, you wished a tool existed, or you abandoned a path. It returns no task data and fixes nothing. Generate a fresh ULID submissionId and reuse the exact request for retries within 24 hours. Field paths must be real SpellBook response paths. There is no free-text field: never describe the card, price, customer, or conversation.

outcomestring, required

What happened to the task: closed enum. Required.

occurredAtstring, required

ISO-8601 timestamp of when the gap occurred. Required.

neededFieldsarray, required

Real SpellBook response field paths that were null or missing when needed. Omit or send empty when none applied.

submissionIdstring, required

A fresh ULID for this report. Reuse the exact same value and request body to retry within 24 hours; a new value starts a new report.

taskCategorystring, required

Which closed task category this gap happened in. Required.

consentToShareboolean, required

True only after the person explicitly agreed to send this specific report.

abandonReasonstring

Why the task was abandoned. Required only when outcome is abandoned.

guessedFieldsarray

Real SpellBook response field paths the agent had to guess a value for because no tool supplied one. Omit when nothing was guessed.

wishedCapabilityobject

A capability the agent wished existed and did not find. Omit when no capability was missing.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

SpellBook Finance MCP server | mcptry

SpellBook Finance

Working · 1.7 s

com.spellbook-finance/mcpv1.0.0 Domain verified

Magic: The Gathering card prices, movers, arbitrage, sealed box EV, and seller inventory tools.

Entertainment & Games

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://api.spellbook-finance.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

spellbook_agent_gap_report

outcomestring, required

What happened to the task: closed enum. Required.

occurredAtstring, required

ISO-8601 timestamp of when the gap occurred. Required.

neededFieldsarray, required

Real SpellBook response field paths that were null or missing when needed. Omit or send empty when none applied.

submissionIdstring, required

A fresh ULID for this report. Reuse the exact same value and request body to retry within 24 hours; a new value starts a new report.

taskCategorystring, required

Which closed task category this gap happened in. Required.

consentToShareboolean, required

True only after the person explicitly agreed to send this specific report.

abandonReasonstring

Why the task was abandoned. Required only when outcome is abandoned.

guessedFieldsarray

Real SpellBook response field paths the agent had to guess a value for because no tool supplied one. Omit when nothing was guessed.

wishedCapabilityobject

A capability the agent wished existed and did not find. Omit when no capability was missing.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

Tools (152)

Tool list last changed Oct 25, 2026.

spellbook_agent_gap_report

Argument	Type	Description
outcome*	string	What happened to the task: closed enum. Required.
occurredAt*	string	ISO-8601 timestamp of when the gap occurred. Required.
neededFields*	array	Real SpellBook response field paths that were null or missing when needed. Omit or send empty when none applied.
submissionId*	string	A fresh ULID for this report. Reuse the exact same value and request body to retry within 24 hours; a new value starts a new report.
taskCategory*	string	Which closed task category this gap happened in. Required.
abandonReason	string	Why the task was abandoned. Required only when outcome is abandoned.
guessedFields	array	Real SpellBook response field paths the agent had to guess a value for because no tool supplied one. Omit when nothing was guessed.
consentToShare*	boolean	True only after the person explicitly agreed to send this specific report.
wishedCapability	object	A capability the agent wished existed and did not find. Omit when no capability was missing.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "consentToShare",
    "submissionId",
    "occurredAt",
    "taskCategory",
    "neededFields",
    "outcome"
  ],
  "properties": {
    "outcome": {
      "enum": [
        "completed",
        "completed_with_guess",
        "abandoned"
      ],
      "type": "string",
      "description": "What happened to the task: closed enum. Required."
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "maxLength": 30,
      "description": "ISO-8601 timestamp of when the gap occurred. Required."
    },
    "neededFields": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 25,
      "description": "Real SpellBook response field paths that were null or missing when needed. Omit or send empty when none applied."
    },
    "submissionId": {
      "type": "string",
      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
      "description": "A fresh ULID for this report. Reuse the exact same value and request body to retry within 24 hours; a new value starts a new report."
    },
    "taskCategory": {
      "enum": [
        "valuation",
        "sell_decision",
        "portfolio_review",
        "acquisition",
        "inventory_placement",
        "other"
      ],
      "type": "string",
      "description": "Which closed task category this gap happened in. Required."
    },
    "abandonReason": {
      "enum": [
        "field_was_null",
        "data_too_stale",
        "no_matching_rows",
        "identity_ambiguous",
        "access_denied",
        "tool_error",
        "no_such_capability",
        "too_many_steps",
        "other"
      ],
      "type": "string",
      "description": "Why the task was abandoned. Required only when outcome is abandoned."
    },
    "guessedFields": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120
      },
      "maxItems": 25,
      "description": "Real SpellBook response field paths the agent had to guess a value for because no tool supplied one. Omit when nothing was guessed."
    },
    "consentToShare": {
      "type": "boolean",
      "const": true,
      "description": "True only after the person explicitly agreed to send this specific report."
    },
    "wishedCapability": {
      "type": "object",
      "required": [
        "category",
        "slug"
      ],
      "properties": {
        "slug": {
          "type": "string",
          "pattern": "^[a-z_]{3,40}$",
          "description": "A lowercase, underscore slug from the fixed capability vocabulary naming what was wished for."
        },
        "category": {
          "enum": [
            "data_field",
            "filter_or_sort",
            "freshness",
            "coverage",
            "export",
            "write_action",
            "other"
          ],
          "type": "string",
          "description": "Which closed capability category was wished for. Required when wishedCapability is present."
        }
      },
      "description": "A capability the agent wished existed and did not find. Omit when no capability was missing.",
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

spellbook_agent_pricing_protection

Read a workspace's saved-rule pricing authority before an eBay reprice. Returns current and accepted eBay rules, mode, source-change acceptance requirement, unresolved submission evidence, missingFields and limitations. Settling means earlier admitted marketplace writes may still finish. Only the owner can accept rules through the web app.

read-only

Argument	Type	Description
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_alert_create

Create one alert in a workspace and return the saved alert. alertType buylist_watch watches dealer buy offers for the whole inventory (buylistWatchScope inventory) or for one printing and finish (buylistWatchScope card); buylistWatchCondition crossed also needs direction and threshold in USD. Every other alertType watches one card or box and needs assetType, assetKey, assetName, isFoil, direction and threshold. Sending the same alert twice returns the first one with replayed true and creates nothing. Call spellbook_alerts_list first to see what exists.

Argument	Type	Description
finish	string	The finish to watch, matching the finish codes spellbook_printings_search returns. Required for a buylist_watch with scope card.
isFoil	boolean	Whether the watched card is foil. Required for every non-buylist_watch type.
assetKey	string	The printing id for a card or the product id for a box. Required for every non-buylist_watch type.
alertType*	string	The kind of alert. buylist_watch watches dealer buy offers against inventory or one printing. Required.
assetName	string	A display name for the watched asset. Required for every non-buylist_watch type. Optional for buylist_watch.
assetType	string	Whether the alert watches a card or a sealed box. Required for every non-buylist_watch type.

spellbook_alert_delete

Delete one saved alert by exact alertId, taken from spellbook_alerts_list, and return success. The alert stops watching at once. Read the list first and confirm with the person which alert to remove, because this tool cannot restore it.

destructive

Argument	Type	Description
alertId*	string	The alertId of the alert to delete, from spellbook_alerts_list. Required.
workspaceId*	string	The workspace the alert belongs to, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "alertId"
  ],
  "properties": {
    "alertId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The alertId of the alert to delete, from spellbook_alerts_list. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the alert belongs to, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_alerts_list

Read every price alert and buylist watch saved in one workspace, one row per alert with its type, asset, direction and threshold when it has them, status, trigger fields and last matched keys. Filter by status or alertType. Call it before spellbook_alert_create to see what the seller already watches, and use the alertId on a row with spellbook_alert_delete. It reports saved alerts and does not evaluate them or say whether a price would trigger one today.

read-only

Argument	Type	Description
status	string	Return only alerts in this status. Omit to include every status.
alertType	string	Return only alerts of this type, such as buylist_watch. Omit to include every type.
workspaceId*	string	The workspace whose alerts to read, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "status": {
      "enum": [
        "active",
        "triggered",
        "disabled"
      ],
      "type": "string",
      "description": "Return only alerts in this status. Omit to include every status."
    },
    "alertType": {
      "enum": [
        "price",
        "metagame",
        "supply_signal",
        "eu_spread",
        "buylist_spread",
        "buylist_vs_cost_basis",
        "spread_compression",
        "restock",
        "velocity",
        "ebay_divergence",
        "fair_value_divergence",
        "delivery_dip",
        "sealed_breakeven_positive",
        "buylist_watch"
      ],
      "type": "string",
      "description": "Return only alerts of this type, such as buylist_watch. Omit to include every type."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose alerts to read, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ath_observations

Read retained Magic card-level high-price detector observations for seven explicit UTC dates and one finish. Use it for which Magic cards hit an all-time high this week. Returns reported USD values, percent-unit changes, catalog-checked Magic labels, publication dates, missing days and coverage limits. Defaults to seven dates ending today and regular finish. Stored ATH state is per oracleId and finish; the reported printing label does not establish which printing supplied the historical price. Read guideResourceUri through MCP for metric, date and identity interpretation. Observations are not independently verified market-wide lifetime highs or trade recommendations.

read-only

Argument	Type	Description
endDate	string	Last inclusive UTC date, YYYY-MM-DD. Omit for today. Exactly six earlier dates are also requested; missing dates stay missing.
priceType	string	Requested finish. Defaults to regular (nonfoil); foil is a separate read.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "endDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last inclusive UTC date, YYYY-MM-DD. Omit for today. Exactly six earlier dates are also requested; missing dates stay missing."
    },
    "priceType": {
      "enum": [
        "regular",
        "foil"
      ],
      "type": "string",
      "default": "regular",
      "description": "Requested finish. Defaults to regular (nonfoil); foil is a separate read."
    }
  },
  "additionalProperties": false
}

spellbook_box_breakeven

Read the existing cash-recovery scenario for one exact sealed product and caller-supplied total cost. Use it for modeled after-cost recovery and break-even timing, separately from gross opening EV or a probability of profit. Resolve the numeric product id with spellbook_sealed_product_search first. Returns the supplied assumptions, quantity, model horizon, source coverage, USD results and unknown clocks. Read the returned guideResourceUri for interpreting conditional price ceilings and a missing crossing. This read does not select a purchase price or recommend opening a product.

read-only

Argument	Type	Description
sellerMode	string	Existing recovery-assumption preset. It changes modeled haircuts and tail timing; it does not verify the caller's seller performance. Defaults to typical.
boxQuantity	integer	Quantity of the exact sealed product, from 1 to 10000. Results are totals for this quantity, not per box. Defaults to one.
costBasisUsd*	number	Positive caller-assumed total acquisition cost in USD for the entire requested quantity, including any inbound costs the caller chooses. Required; no catalog-price default.
tcgProductId*	string	Exact numeric sealed-product id from spellbook_sealed_product_search. A display, case and pack have different ids.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "tcgProductId",
    "costBasisUsd"
  ],
  "properties": {
    "sellerMode": {
      "enum": [
        "conservative",
        "typical",
        "high_throughput"
      ],
      "type": "string",
      "default": "typical",
      "description": "Existing recovery-assumption preset. It changes modeled haircuts and tail timing; it does not verify the caller's seller performance. Defaults to typical."
    },
    "boxQuantity": {
      "type": "integer",
      "default": 1,
      "maximum": 10000,
      "minimum": 1,
      "description": "Quantity of the exact sealed product, from 1 to 10000. Results are totals for this quantity, not per box. Defaults to one."
    },
    "costBasisUsd": {
      "type": "number",
      "maximum": 1000000000,
      "description": "Positive caller-assumed total acquisition cost in USD for the entire requested quantity, including any inbound costs the caller chooses. Required; no catalog-price default.",
      "exclusiveMinimum": 0
    },
    "tcgProductId": {
      "type": "string",
      "pattern": "^[1-9]\\d{0,11}$",
      "description": "Exact numeric sealed-product id from spellbook_sealed_product_search. A display, case and pack have different ids."
    }
  },
  "additionalProperties": false
}

spellbook_box_ev_history

Read stored daily gross opening-EV observations for one exact sealed product. Use it when asked how a named box's EV changed over time. Resolve the product with spellbook_sealed_product_search first; pass its numeric tcgProductId. Returns product identity, requested dates, USD values per sealed product, dated source rows and explicit model/freshness gaps. Missing dates stay absent. Read guideResourceUri through MCP for date, valuation and model interpretation. An older history point is not today's EV. The response establishes no price-only cause or unchanged methodology.

read-only

Argument	Type	Description
days	integer	Lookback in days, from 1 to 365. Defaults to 183 days; calendar-month lengths vary. The returned window gives the actual inclusive UTC dates.
tcgProductId*	string	Exact numeric TCGplayer sealed-product id from spellbook_sealed_product_search. Required; do not pass a card id or product name.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "tcgProductId"
  ],
  "properties": {
    "days": {
      "type": "integer",
      "default": 183,
      "maximum": 365,
      "minimum": 1,
      "description": "Lookback in days, from 1 to 365. Defaults to 183 days; calendar-month lengths vary. The returned window gives the actual inclusive UTC dates."
    },
    "tcgProductId": {
      "type": "string",
      "pattern": "^[1-9]\\d{0,11}$",
      "description": "Exact numeric TCGplayer sealed-product id from spellbook_sealed_product_search. Required; do not pass a card id or product name."
    }
  },
  "additionalProperties": false
}

spellbook_box_ev_rankings

Read a named sealed product's modeled gross contents EV, or compare ranking rows, with totalEV, evRatio, pack standard deviation (packSD), N0 and breakEvenPct. For a named Collector Booster display, use q and box_type, then match boxId to the exact catalog product; a Collector's Edition Commander deck is a different product. Default order is highest evRatio first. Call it for "how many packs until opening is likely profitable" (N0), "how swingy is this box" (packSD, and swinginess, which is packSD divided by packEV) and "what share of packs beat the pack price" (breakEvenPct). N0 is the number of packs at which a normal approximation, treating packs as independent and identical, gives about a 97.7% modeled probability that summed card value under the selected valuation basis exceeds summed pack cost. It is null when required inputs are absent or matching edge or standard deviation is not positive. Pack cost is the returned packPrice: a separate stored pack reference when available, otherwise box marketPrice divided by packsPerBox. Preserve packPriceSource; a missing or unrecognized label leaves the reference origin unknown. This is not a caller-paid cost. Each N0 variant uses its own valuation basis, with its own pack SD and edge: n0Full uses full market value (packSD, fullEdge), n0LandAdjusted prices cheap lands at bulk rates (landAdjustedPackSD, landAdjustedEdge), and n0Sellable prices cards below a threshold at bulk buylist rates (sellablePackSD, sellableEdge). These valuations use their stated basis before selling fees, shipping and liquidity. breakEvenPct is the share of simulated single packs worth at least packPrice. It is not the probability of profit after N packs. Rows also carry exact product IDs, market prices, the acquirableFloorUsd and evRatioBasis behind the stored EV ratios when present, market-basis ratios, market-price spreads, shipping-aware ratios, per-pack metrics and row timestamps. evRatio is totalEV divided by max(marketPrice, the cheapest captured TCG listing price plus shipping) on rows with a known basis; evRatioMarketBasis preserves the market-price comparison. spreadUsd is totalEV minus marketPrice, so it is a separate comparison. typicalEV is the box EV with every card under typicalEvCutoffPerPack (a pull probability of 0.001 per pack) left out, and typicalEvExcludedCount is how many cards that dropped; typicalEV is null when the model cannot compute it, with typicalEvReason saying why. Sort by n0Full, n0LandAdjusted or n0Sellable to order boxes by packs needed. Call spellbook_sealed_product_offers with a row's boxId for store offers on that product. For valuation, product identity and source-clock context, read guideResourceUri through MCP; guideUrl is the same published page. A catalog entry is not its full guide body. This is modeled research evidence for a caller's decision, not a purchase instruction.

spellbook_box_price_history

Read dated TCGCSV reference-price observations for one exact sealed box/display and an explicit historical window. Use it for a named box's price change or a retained launch-date baseline. Resolve the numeric product with spellbook_sealed_product_search first. Returns the requested identity, dates, USD Market/Low/Mid when stored, missing dates and unknown clocks. Read guideResourceUri through MCP before interpreting a since-release comparison. Use separate narrow calls for distant endpoints; the read supplies no official release date, price-change cause or realized return.

read-only

Argument	Type	Description
to*	string	Required inclusive real UTC end date, YYYY-MM-DD. Must follow or equal from, no more than 365 days later. Use separate narrow calls for distant endpoints.
from*	string	Required inclusive real UTC start date, YYYY-MM-DD. Historical windows may precede the last year.
tcgProductId*	string	Exact numeric box/display id returned by sealed product search. A case or loose pack differs.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "tcgProductId",
    "from",
    "to"
  ],
  "properties": {
    "to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required inclusive real UTC end date, YYYY-MM-DD. Must follow or equal from, no more than 365 days later. Use separate narrow calls for distant endpoints."
    },
    "from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Required inclusive real UTC start date, YYYY-MM-DD. Historical windows may precede the last year."
    },
    "tcgProductId": {
      "type": "string",
      "pattern": "^[1-9]\\d{0,11}$",
      "description": "Exact numeric box/display id returned by sealed product search. A case or loose pack differs."
    }
  },
  "additionalProperties": false
}

spellbook_buy_outcome_report

Score every closed buy decision in one workspace against its immutable prediction and a fixed equal-weight printing basket. Includes unscored and abandoned counts, missing baseline evidence and small-sample limits. Uses submitted receipts; does not verify merchant orders or money.

read-only

Argument	Type	Description
workspaceId*	string	The workspaceId to score, from spellbook_workspaces_list. Required; this scores exactly one workspace.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspaceId to score, from spellbook_workspaces_list. Required; this scores exactly one workspace."
    }
  },
  "additionalProperties": false
}

spellbook_buy_targets

Return a bounded source-order page of materialized TCGplayer-to-Card-Kingdom rows with an opaque nextCursor for complete traversal. Rows include printing identity, observed acquisition and cash quote prices, listed shipping, seller/quantity evidence, exit.quantityBuying (the copies Card Kingdom buys at the quoted price), maxCopies (the smaller of listed stock and exit.quantityBuying), the Card Kingdom condition ladder (NM/EX/VG/G payouts, modeled from the NM quote), timestamps, printingMismatches and missingFields. Call this first when a person says "I have $X to risk", "find me opportunities", "good opportunities", "single cards", "high risk singles", "start with arbitrage" or "what should I buy". Never request more copies of a row than maxCopies. Before handing a person a buy list, record each chosen row as a consideration with spellbook_customer_evidence_record, because spellbook_buy_outcome_report scores only recorded considerations. No profit, ranking, selection, reserves or cost defaults. Exact listing links and fee amounts are null when unavailable. Customer agent supplies all policy and executes purchases.

read-only

Argument	Type	Description
limit	integer	Maximum buy-target rows to return, 1 to 200. Omit for the default of 200.
cursor	string	Opaque nextCursor from a previous page, passed back unchanged to continue traversal. Omit to start from the first page.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 200,
      "maximum": 200,
      "minimum": 1,
      "description": "Maximum buy-target rows to return, 1 to 200. Omit for the default of 200."
    },
    "cursor": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "Opaque nextCursor from a previous page, passed back unchanged to continue traversal. Omit to start from the first page."
    }
  },
  "additionalProperties": false
}

spellbook_buylist_compare

Read one page of a workspace's sellable inventory, one group per printing, finish and condition, with the per-unit net at each of seven destinations: Card Kingdom cash, Card Kingdom credit, Star City Games cash, ManaPool, TCGplayer, TCGplayer Direct and eBay. Each destination carries gross, fees, net, price source, observation time, vendor minimum, quantity the vendor is buying and a skip reason when it has no usable price. Pass nextCursor back to read the next page. It lists every destination in a fixed order and does not rank them, name a best one or say what to sell.

read-only

Argument	Type	Description
limit	integer	Maximum groups to return, 1 to 500. Omit for the server default.
cursor	string	Opaque nextCursor from a previous page, passed back unchanged. Omit to start from the first page.
workspaceId*	string	The workspace whose inventory to compare, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 500,
      "minimum": 1,
      "description": "Maximum groups to return, 1 to 500. Omit for the server default."
    },
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque nextCursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose inventory to compare, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_buyouts

Read Magic price-spike observations from SpellBook Finance's buyout detector. Call it when asked which Magic cards are being bought out right now. Returns printing identity, old and new USD prices, fractional pctGain (0.25 means 25%), detection time, secondary-source confirmation, source links and explicit coverage gaps. Read guideResourceUri through MCP for interpretation and stop conditions. If guideUrl fails in a browser, spellbook_guides also discovers the guide's resourceUri. Observations are candidates, not verified buyouts. Call spellbook_card_prices with a row's scryfallId for current per-source price observations.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_card_buylist

Read dealer buy offers for ONE exact card product, preserving each offer's game, finish, subtype, language, condition, source product, source timestamp, cash and credit fields, quantity and missingFields. Use the catalog product id from spellbook_printings_search. Pokemon offers are English NM/New CoolStuffInc observations when present; no offer or missing field proves a dealer has no stock. This read returns facts and does not choose a vendor or sell cards.

read-only

Argument	Type	Description
cardId*	string	The exact printing or catalog product id from spellbook_printings_search. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "cardId"
  ],
  "properties": {
    "cardId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The exact printing or catalog product id from spellbook_printings_search. Required."
    }
  },
  "additionalProperties": false
}

spellbook_card_buylist_history

Read the stored daily dealer buylist price series for ONE exact printing: one point per day with the Card Kingdom and Cardhoarder buylist price when SpellBook stored one, oldest day first, plus earliestDay, the first day SpellBook holds any stored row for that printing. Use the printing id from spellbook_printings_search. Call spellbook_card_buylist for current offers from every dealer SpellBook reads. This read returns facts; it does not choose a vendor, judge a price or sell cards.

read-only

Argument	Type	Description
days	integer	How many days back to read, 1 to 180. Omit for the longest window SpellBook returns.
cardId*	string	The exact printing id from spellbook_printings_search. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "cardId"
  ],
  "properties": {
    "days": {
      "type": "integer",
      "maximum": 180,
      "minimum": 1,
      "description": "How many days back to read, 1 to 180. Omit for the longest window SpellBook returns."
    },
    "cardId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The exact printing id from spellbook_printings_search. Required."
    }
  },
  "additionalProperties": false
}

spellbook_card_desk

Read ONE Magic printing's stored daily price series, its recent sales and its current TCGplayer asks. Every caller gets all three, signed in or not. tcgplayerProductId is the exact printing's TCGplayer product id when known. series has one point per stored day, oldest first: priceUsd is the TCGplayer Market price SpellBook stored that day and tcgLow is the TCGplayer Low price. buckets sums Near Mint and Lightly Played sales of the requested finish with English or unspecified language by the exact raw bucketStartDate values returned by TCGplayer. The source response does not establish each bucket's duration or end date. Each row has units, transactions, a units-weighted bucket market and the lowest and highest recorded sale. If qualifying sold rows have unspecified language, limitations says so; known non-English rows are excluded. bucketsState distinguishes no stored fetch from an observed fetch; bucketsCoverage gives the first and last stored bucket dates when available. asks lists the TCGplayer listings of the requested finish from the newest unexpired snapshot, cheapest first, with item price, condition, language when known, listing shipping when known, quantity and seller name. asksTotal and asksTruncated report the source row count and truncation status when known. Each evidence family carries its own captured time. Call it after spellbook_printings_search names the printing, to see how its price moved over weeks or to compare its market series with recent sales and asks. Call spellbook_card_prices for today's price from every other source. It returns observations and limitations; it does not rank or recommend a printing. Compute any band, return or range yourself from series.

read-only

Argument	Type	Description
cardId*	string	The exact Magic printing id (a Scryfall UUID) from spellbook_printings_search. Required.
finish	string	Which finish to read. Omit for nonfoil. Pass foil for a foil copy, because SpellBook stores foil prices, sales and asks apart from nonfoil.

spellbook_card_prices

Read every price source SpellBook Finance holds for ONE printing, one row per source, each with its own label, price and timestamp. Sources can include TCGplayer Market, TCGplayer Low, Card Kingdom retail and buylist, CoolStuff, an eBay 90-day sold median, Cardmarket, ManaPool and CardTrader. Pokemon TCGplayer finish subtypes stay in separate rows. cardId is the exact printing id returned by spellbook_printings_search: a UUID for Magic, or a catalog product id for Riftbound or Pokemon. Rows come back in source order with their own timestamps; nothing is averaged, ranked, or chosen for you, and no listing link is returned. For Market-versus-dealer interpretation, find a guide with spellbook_guides topic buylist-and-exits. EUR rows include the conversion rate and its recorded date/source when available. Read the returned guideResourceUri for currency and source-metric context; MCP resource retrieval is an alternative if guideUrl cannot be fetched. It is discoverable with spellbook_guides topic pricing.

read-only

Argument	Type	Description
cardId*	string	The exact printing id from spellbook_printings_search: a UUID for Magic, or the namespaced catalog product id for Riftbound or Pokemon. Required.
finish	string	Which finish of a Magic printing to price. Omit for nonfoil. Pass foil or etched when the copy in question is foil or etched, because a foil copy often sells at a different price. Riftbound and Pokemon ignore it and return every finish as its own rows.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "cardId"
  ],
  "properties": {
    "cardId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The exact printing id from spellbook_printings_search: a UUID for Magic, or the namespaced catalog product id for Riftbound or Pokemon. Required."
    },
    "finish": {
      "enum": [
        "nonfoil",
        "foil",
        "etched"
      ],
      "type": "string",
      "description": "Which finish of a Magic printing to price. Omit for nonfoil. Pass foil or etched when the copy in question is foil or etched, because a foil copy often sells at a different price. Riftbound and Pokemon ignore it and return every finish as its own rows."
    }
  },
  "additionalProperties": false
}

spellbook_channel_lane_set

Set one workspace's lane mode for one channel-lane marketplace, the switch that decides whether SpellBook reads the marketplace or changes listings there. This changes public marketplace behavior for the workspace, only the workspace owner may call it, and the agent sets a mode only after the seller chose one. It returns the same lane state as spellbook_marketplace_onboarding. The modes: off: the lane is disabled and SpellBook neither reads nor changes the marketplace. observe: SpellBook reads the marketplace and records whether it matches SpellBook's desired state, and never changes a listing there. push: SpellBook creates, updates, and removes listings on the marketplace to match its desired state.

destructive

Argument	Type	Description
mode*	string	The mode the seller chose: off, observe, or push. Required.
marketplace*	string	The channel-lane marketplace whose mode to set. Required.
workspaceId*	string	The workspace whose lane to set. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "marketplace",
    "mode"
  ],
  "properties": {
    "mode": {
      "enum": [
        "off",
        "observe",
        "push"
      ],
      "type": "string",
      "description": "The mode the seller chose: off, observe, or push. Required."
    },
    "marketplace": {
      "enum": [
        "cardtrader",
        "ebay",
        "manapool",
        "misprint",
        "shopify"
      ],
      "type": "string",
      "description": "The channel-lane marketplace whose mode to set. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose lane to set. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_channel_pricing_profile_set

Pin one of the workspace's saved pricing profiles to one marketplace channel, or clear the pin with a null profileId. It is the same choice as the channel defaults card on the SpellBook pricing settings page. Read spellbook_channel_pricing_profiles first, and pin only a profile the seller named. Returns the full channel pricing read after the write, plus the channel's previous pin, so the change can be reverted by setting the previous value back. It changes which profile prices future automatic listings and reprices; it edits no profile and publishes nothing.

destructive

Argument	Type	Description
channel*	string	The marketplace channel to pin: ebay, tcg (TCGplayer), manapool, shopify or cardtrader. Required.
profileId*	any	A profileId from spellbook_channel_pricing_profiles, or null to clear the pin so the channel falls back to the workspace's active profile. Required.
workspaceId*	string	The workspace to change, from spellbook_workspaces_list. The signed-in customer must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "channel",
    "profileId"
  ],
  "properties": {
    "channel": {
      "enum": [
        "ebay",
        "tcg",
        "manapool",
        "shopify",
        "cardtrader"
      ],
      "type": "string",
      "description": "The marketplace channel to pin: ebay, tcg (TCGplayer), manapool, shopify or cardtrader. Required."
    },
    "profileId": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "description": "A profileId from spellbook_channel_pricing_profiles, or null to clear the pin so the channel falls back to the workspace's active profile. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to change, from spellbook_workspaces_list. The signed-in customer must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_channel_pricing_profiles

Read which saved pricing profile each marketplace channel prices from in one workspace. Automatic eBay listing and repricing price every card from the eBay channel's profile, so read this before a seller turns on automatic eBay listing. Returns the workspace's saved profiles by name with the active one marked, and for each channel the pinned profile, the profile automation actually prices from, and which SpellBook jobs read that pin. It reports the setting and recommends no profile.

read-only

Argument	Type	Description
workspaceId*	string	The workspace to read, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to read, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_collection_buying_get

Read the current snapshot or one immutable revision of a collection deal owned by the selected workspace. The response includes the selected revision's command and receiptId so submitted terms and corrections can be audited. Read the collection-buying skill before interpreting lifecycle state.

read-only

Argument	Type	Description
dealId*	string	Exact dealId from a record or list response. Required.
revision	integer	One immutable revision number. Omit for the latest snapshot.
workspaceId*	string	The seller-owned workspace. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "dealId"
  ],
  "properties": {
    "dealId": {
      "type": "string",
      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
      "description": "Exact dealId from a record or list response. Required."
    },
    "revision": {
      "type": "integer",
      "maximum": 100000,
      "minimum": 1,
      "description": "One immutable revision number. Omit for the latest snapshot."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller-owned workspace. Required."
    }
  },
  "additionalProperties": false
}

spellbook_collection_buying_list

List a bounded page of collection deals in the selected seller workspace. Follow nextCursor to enumerate the full set, then read a deal for its latest or historical revision and source command.

read-only

Argument	Type	Description
limit	integer	Maximum deals on this page, 1 to 50. Omit for the default of 20.
cursor	string	Opaque nextCursor from the previous page. Pass unchanged to continue; omit for the first page.
workspaceId*	string	The seller-owned workspace. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum deals on this page, 1 to 50. Omit for the default of 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque nextCursor from the previous page. Pass unchanged to continue; omit for the first page."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller-owned workspace. Required."
    }
  },
  "additionalProperties": false
}

spellbook_collection_buying_record

Record one seller-agreed collection deal or a later receipt, count correction, evaluation, seller response, reported payment/refund, return/title disposition, dispute, closure, or evidence-backed reopening. Read spellbook_skill(name: collection-buying) first. A submission is an immutable, owner-scoped receipt; retry its exact submissionId and payload after an uncertain result. It records evidence only: it does not contact a seller, send money, verify a reported payment, transfer title, receive inventory, or publish cards.

Argument	Type	Description
command*	any	One lifecycle command with a fresh submissionId and occurredAt. After open, supply dealId and expectedRevision.
workspaceId*	string	The seller-owned workspace to record this deal in. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "command"
  ],
  "properties": {
    "command": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "open",
              "description": "Start after the seller has agreed to the recorded terms."
            },
            "payload": {
              "type": "object",
              "required": [
                "source",
                "sourceReference",
                "sellerLabel",
                "agreement"
              ],
              "properties": {
                "source": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Where the deal originated."
                },
                "agreement": {
                  "type": "object",
                  "required": [
                    "commitment",
                    "sellerAcceptedAt",
                    "sellerAcceptanceEvidence",
                    "titleTransferPoint",
                    "paymentTiming",
                    "buckets"
                  ],
                  "properties": {
                    "buckets": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "categories",
                              "kind",
                              "amountUsd"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 80,
                                "minLength": 1,
                                "description": "Unique price bucket id."
                              },
                              "kind": {
                                "type": "string",
                                "const": "fixed_lot"
                              },
                              "amountUsd": {
                                "type": "number",
                                "maximum": 10000000,
                                "minimum": 0,
                                "multipleOf": 0.01,
                                "description": "Flat price for the complete accepted lot, in USD."
                              },
                              "categories": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "category",
                                    "expectedQuantity"
                                  ],
                                  "properties": {
                                    "category": {
                                      "type": "string",
                                      "maxLength": 80,
                                      "minLength": 1,
                                      "description": "Physical category in this bucket."
                                    },
                                    "expectedQuantity": {
                                      "type": "integer",
                                      "maximum": 100000,
                                      "minimum": 0,
                                      "description": "Known agreed quantity for this fixed lot."
                                    }
                                  },
                                  "additionalProperties": false
                                },
                                "maxItems": 50,
                                "minItems": 1,
                                "description": "Disjoint physical categories covered by the flat lot price."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "categories",
                              "kind",
                              "amountUsd"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 80,
                                "minLength": 1,
                                "description": "Unique price bucket id."
                              },
                              "kind": {
                                "type": "string",
                                "const": "per_unit"
                              },
                              "amountUsd": {
                                "type": "number",
                                "maximum": 10000,
                                "minimum": 0,
                                "multipleOf": 0.000001,
                                "description": "USD per accepted physical unit, up to six decimal places."
                              },
                              "categories": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "category",
                                    "expectedQuantity"
                                  ],
                                  "properties": {
                                    "category": {
                                      "type": "string",
                                      "maxLength": 80,
                                      "minLength": 1,
                                      "description": "Stable physical category identifier."
                                    },
                                    "expectedQuantity": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "maximum": 100000,
                                          "minimum": 0
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ],
                                      "description": "Agreed quantity, or null when the lot size is unknown."
                                    }
                                  },
                                  "additionalProperties": false
                                },
                                "maxItems": 50,
                                "minItems": 1,
                                "description": "Disjoint physical categories priced at this unit rate."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "categories",
                              "kind",
                              "percentage",
                              "basis"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 80,
                                "minLength": 1,
                                "description": "Unique price bucket id."
                              },
                              "kind": {
                                "type": "string",
                                "const": "percent_market"
                              },
                              "basis": {
                                "type": "object",
                                "required": [
                                  "source",
                                  "timeBasis",
                                  "conditionBasis",
                                  "finishBasis"
                                ],
                                "properties": {
                                  "source": {
                                    "type": "string",
                                    "maxLength": 200,
                                    "minLength": 1,
                                    "description": "Exact source used for the market quote."
                                  },
                                  "timeBasis": {
                                    "enum": [
                                      "agreement",
                                      "evaluation",
                                      "handover"
                                    ],
                                    "type": "string",
                                    "description": "Quote timing contract."
                                  },
                                  "finishBasis": {
                                    "enum": [
                                      "actual_finish",
                                      "nonfoil",
                                      "foil",
                                      "etched",
                                      "unknown"
                                    ],
                                    "type": "string",
                                    "description": "Finish basis used by the quote."
                                  },
                                  "conditionBasis": {
                                    "enum": [
                                      "actual_condition",
                                      "near_mint",
                                      "lightly_played",
                                      "moderately_played",
                                      "heavily_played",
                                      "damaged",
                                      "unknown"
                                    ],
                                    "type": "string",
                                    "description": "Condition basis used by the quote."
                                  }
                                },
                                "description": "Explicit source, time, condition and finish basis; unknown is not a usable quote.",
                                "additionalProperties": false
                              },
                              "categories": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "category",
                                    "expectedQuantity"
                                  ],
                                  "properties": {
                                    "category": {
                                      "type": "string",
                                      "maxLength": 80,
                                      "minLength": 1,
                                      "description": "Stable physical category identifier."
                                    },
                                    "expectedQuantity": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "maximum": 100000,
                                          "minimum": 0
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ],
                                      "description": "Agreed quantity, or null when the lot size is unknown."
                                    }
                                  },
                                  "additionalProperties": false
                                },
                                "maxItems": 50,
                                "minItems": 1,
                                "description": "Disjoint physical categories priced from exact market marks."
                              },
                              "percentage": {
                                "type": "number",
                                "maximum": 100,
                                "minimum": 0,
                                "multipleOf": 0.01,
                                "description": "Agreed percentage of the market mark."
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      },
                      "maxItems": 25,
                      "minItems": 1,
                      "description": "Disjoint fixed-lot, decimal unit-rate, or explicit market-percentage price buckets."
                    },
                    "commitment": {
                      "enum": [
                        "binding_formula",
                        "estimate_then_offer"
                      ],
                      "type": "string",
                      "description": "Whether accepted terms bind a formula or require seller acceptance of the exact evaluation."
                    },
                    "paymentTiming": {
                      "enum": [
                        "upfront",
                        "at_handover",
                        "after_evaluation",
                        "deposit_then_balance",
                        "other"
                      ],
                      "type": "string",
                      "description": "Agreed payment timing."
                    },
                    "sellerAcceptedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                      "maxLength": 30,
                      "description": "Time seller accepted these exact agreement terms."
                    },
                    "titleTransferPoint": {
                      "enum": [
                        "seller_acceptance",
                        "payment",
                        "handover"
                      ],
                      "type": "string",
                      "description": "Agreed title-transfer trigger; this ledger never performs a transfer."
                    },
                    "sellerAcceptanceEvidence": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Short evidence note for seller acceptance."
                    }
                  },
                  "description": "Agreed buckets, accepted terms and title/payment triggers.",
                  "additionalProperties": false
                },
                "sellerLabel": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Customer's short seller label."
                },
                "sourceReference": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 300
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Listing or conversation reference, or null."
                }
              },
              "description": "Agreed deal and seller evidence.",
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "receipt",
              "description": "Add newly received physical counts."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "counts",
                "provenance",
                "evidence"
              ],
              "properties": {
                "counts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "category",
                      "quantity",
                      "countMethod",
                      "scanCoverage"
                    ],
                    "properties": {
                      "category": {
                        "type": "string",
                        "maxLength": 80,
                        "minLength": 1,
                        "description": "Agreed physical category."
                      },
                      "quantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 1,
                        "description": "Physically counted quantity received in this submission."
                      },
                      "countMethod": {
                        "enum": [
                          "buyer_count",
                          "seller_count",
                          "buyer_estimate",
                          "unique_unit_scan",
                          "mixed"
                        ],
                        "type": "string",
                        "description": "How the physical count was made."
                      },
                      "scanCoverage": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "uniquePhysicalUnitsScanned",
                              "denominatorUnits"
                            ],
                            "properties": {
                              "denominatorUnits": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "maximum": 100000,
                                    "minimum": 0
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Verified counted-unit denominator, or null when unknown."
                              },
                              "uniquePhysicalUnitsScanned": {
                                "type": "integer",
                                "maximum": 100000,
                                "minimum": 0,
                                "description": "Count of unique physical units scanned."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Unique scan count and verified denominator, or null when no scan count is claimed."
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 50,
                  "minItems": 1,
                  "description": "New positive quantities by disjoint category."
                },
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Arrival and count evidence."
                },
                "provenance": {
                  "enum": [
                    "customer_reported",
                    "agent_observed"
                  ],
                  "type": "string",
                  "description": "Evidence source."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "receipt_complete",
              "description": "Confirm the lot has been fully received and counted."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "evidence"
              ],
              "properties": {
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Evidence that all agreed parcels/lot units have arrived and were counted."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "receipt_correction",
              "description": "Correct previously submitted cumulative counts."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "counts",
                "provenance",
                "evidence"
              ],
              "properties": {
                "counts": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "category",
                      "correctedQuantity",
                      "countMethod",
                      "scanCoverage"
                    ],
                    "properties": {
                      "category": {
                        "type": "string",
                        "maxLength": 80,
                        "minLength": 1,
                        "description": "Agreed physical category being corrected."
                      },
                      "countMethod": {
                        "enum": [
                          "buyer_count",
                          "seller_count",
                          "buyer_estimate",
                          "unique_unit_scan",
                          "mixed"
                        ],
                        "type": "string",
                        "description": "Method used for the corrected count."
                      },
                      "scanCoverage": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "uniquePhysicalUnitsScanned",
                              "denominatorUnits"
                            ],
                            "properties": {
                              "denominatorUnits": {
                                "anyOf": [
                                  {
                                    "type": "integer",
                                    "maximum": 100000,
                                    "minimum": 0
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Verified counted-unit denominator, or null when unknown."
                              },
                              "uniquePhysicalUnitsScanned": {
                                "type": "integer",
                                "maximum": 100000,
                                "minimum": 0,
                                "description": "Count of unique physical units scanned."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Updated unique scan count and verified denominator, or null when unknown."
                      },
                      "correctedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Replacement cumulative received quantity."
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 50,
                  "minItems": 1,
                  "description": "Replacement quantities for named categories."
                },
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Why the earlier count was wrong."
                },
                "provenance": {
                  "enum": [
                    "customer_reported",
                    "agent_observed"
                  ],
                  "type": "string",
                  "description": "Evidence source."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "amend_agreement",
              "description": "Record seller-accepted amended terms."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "agreement"
              ],
              "properties": {
                "agreement": {
                  "type": "object",
                  "required": [
                    "commitment",
                    "sellerAcceptedAt",
                    "sellerAcceptanceEvidence",
                    "titleTransferPoint",
                    "paymentTiming",
                    "buckets"
                  ],
                  "properties": {
                    "buckets": {
                      "type": "array",
                      "items": {
                        "oneOf": [
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "categories",
                              "kind",
                              "amountUsd"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 80,
                                "minLength": 1,
                                "description": "Unique price bucket id."
                              },
                              "kind": {
                                "type": "string",
                                "const": "fixed_lot"
                              },
                              "amountUsd": {
                                "type": "number",
                                "maximum": 10000000,
                                "minimum": 0,
                                "multipleOf": 0.01,
                                "description": "Flat price for the complete accepted lot, in USD."
                              },
                              "categories": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "category",
                                    "expectedQuantity"
                                  ],
                                  "properties": {
                                    "category": {
                                      "type": "string",
                                      "maxLength": 80,
                                      "minLength": 1,
                                      "description": "Physical category in this bucket."
                                    },
                                    "expectedQuantity": {
                                      "type": "integer",
                                      "maximum": 100000,
                                      "minimum": 0,
                                      "description": "Known agreed quantity for this fixed lot."
                                    }
                                  },
                                  "additionalProperties": false
                                },
                                "maxItems": 50,
                                "minItems": 1,
                                "description": "Disjoint physical categories covered by the flat lot price."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "categories",
                              "kind",
                              "amountUsd"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 80,
                                "minLength": 1,
                                "description": "Unique price bucket id."
                              },
                              "kind": {
                                "type": "string",
                                "const": "per_unit"
                              },
                              "amountUsd": {
                                "type": "number",
                                "maximum": 10000,
                                "minimum": 0,
                                "multipleOf": 0.000001,
                                "description": "USD per accepted physical unit, up to six decimal places."
                              },
                              "categories": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "category",
                                    "expectedQuantity"
                                  ],
                                  "properties": {
                                    "category": {
                                      "type": "string",
                                      "maxLength": 80,
                                      "minLength": 1,
                                      "description": "Stable physical category identifier."
                                    },
                                    "expectedQuantity": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "maximum": 100000,
                                          "minimum": 0
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ],
                                      "description": "Agreed quantity, or null when the lot size is unknown."
                                    }
                                  },
                                  "additionalProperties": false
                                },
                                "maxItems": 50,
                                "minItems": 1,
                                "description": "Disjoint physical categories priced at this unit rate."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "required": [
                              "id",
                              "categories",
                              "kind",
                              "percentage",
                              "basis"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 80,
                                "minLength": 1,
                                "description": "Unique price bucket id."
                              },
                              "kind": {
                                "type": "string",
                                "const": "percent_market"
                              },
                              "basis": {
                                "type": "object",
                                "required": [
                                  "source",
                                  "timeBasis",
                                  "conditionBasis",
                                  "finishBasis"
                                ],
                                "properties": {
                                  "source": {
                                    "type": "string",
                                    "maxLength": 200,
                                    "minLength": 1,
                                    "description": "Exact source used for the market quote."
                                  },
                                  "timeBasis": {
                                    "enum": [
                                      "agreement",
                                      "evaluation",
                                      "handover"
                                    ],
                                    "type": "string",
                                    "description": "Quote timing contract."
                                  },
                                  "finishBasis": {
                                    "enum": [
                                      "actual_finish",
                                      "nonfoil",
                                      "foil",
                                      "etched",
                                      "unknown"
                                    ],
                                    "type": "string",
                                    "description": "Finish basis used by the quote."
                                  },
                                  "conditionBasis": {
                                    "enum": [
                                      "actual_condition",
                                      "near_mint",
                                      "lightly_played",
                                      "moderately_played",
                                      "heavily_played",
                                      "damaged",
                                      "unknown"
                                    ],
                                    "type": "string",
                                    "description": "Condition basis used by the quote."
                                  }
                                },
                                "description": "Explicit source, time, condition and finish basis; unknown is not a usable quote.",
                                "additionalProperties": false
                              },
                              "categories": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "category",
                                    "expectedQuantity"
                                  ],
                                  "properties": {
                                    "category": {
                                      "type": "string",
                                      "maxLength": 80,
                                      "minLength": 1,
                                      "description": "Stable physical category identifier."
                                    },
                                    "expectedQuantity": {
                                      "anyOf": [
                                        {
                                          "type": "integer",
                                          "maximum": 100000,
                                          "minimum": 0
                                        },
                                        {
                                          "type": "null"
                                        }
                                      ],
                                      "description": "Agreed quantity, or null when the lot size is unknown."
                                    }
                                  },
                                  "additionalProperties": false
                                },
                                "maxItems": 50,
                                "minItems": 1,
                                "description": "Disjoint physical categories priced from exact market marks."
                              },
                              "percentage": {
                                "type": "number",
                                "maximum": 100,
                                "minimum": 0,
                                "multipleOf": 0.01,
                                "description": "Agreed percentage of the market mark."
                              }
                            },
                            "additionalProperties": false
                          }
                        ]
                      },
                      "maxItems": 25,
                      "minItems": 1,
                      "description": "Disjoint fixed-lot, decimal unit-rate, or explicit market-percentage price buckets."
                    },
                    "commitment": {
                      "enum": [
                        "binding_formula",
                        "estimate_then_offer"
                      ],
                      "type": "string",
                      "description": "Whether accepted terms bind a formula or require seller acceptance of the exact evaluation."
                    },
                    "paymentTiming": {
                      "enum": [
                        "upfront",
                        "at_handover",
                        "after_evaluation",
                        "deposit_then_balance",
                        "other"
                      ],
                      "type": "string",
                      "description": "Agreed payment timing."
                    },
                    "sellerAcceptedAt": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                      "maxLength": 30,
                      "description": "Time seller accepted these exact agreement terms."
                    },
                    "titleTransferPoint": {
                      "enum": [
                        "seller_acceptance",
                        "payment",
                        "handover"
                      ],
                      "type": "string",
                      "description": "Agreed title-transfer trigger; this ledger never performs a transfer."
                    },
                    "sellerAcceptanceEvidence": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Short evidence note for seller acceptance."
                    }
                  },
                  "description": "Complete replacement agreement; changed terms invalidate the report and receipt completion.",
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "evaluate",
              "description": "Record an itemized acceptance/rejection/unresolved report."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "lines",
                "evidence"
              ],
              "properties": {
                "lines": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "category",
                      "receivedQuantity",
                      "acceptedQuantity",
                      "rejectedQuantity",
                      "unresolvedQuantity",
                      "printing",
                      "marketValue"
                    ],
                    "properties": {
                      "category": {
                        "type": "string",
                        "maxLength": 80,
                        "minLength": 1,
                        "description": "Agreed physical category."
                      },
                      "printing": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "game",
                              "setCode",
                              "collectorNumber",
                              "printingId",
                              "language",
                              "condition",
                              "finish"
                            ],
                            "properties": {
                              "game": {
                                "type": "string",
                                "maxLength": 200,
                                "minLength": 1,
                                "description": "Game name."
                              },
                              "finish": {
                                "enum": [
                                  "nonfoil",
                                  "foil",
                                  "etched",
                                  "unknown"
                                ],
                                "type": "string",
                                "description": "Observed physical finish; unknown stays unknown."
                              },
                              "setCode": {
                                "type": "string",
                                "maxLength": 200,
                                "minLength": 1,
                                "description": "Set code."
                              },
                              "language": {
                                "type": "string",
                                "maxLength": 200,
                                "minLength": 1,
                                "description": "Card language."
                              },
                              "condition": {
                                "enum": [
                                  "near_mint",
                                  "lightly_played",
                                  "moderately_played",
                                  "heavily_played",
                                  "damaged",
                                  "unknown"
                                ],
                                "type": "string",
                                "description": "Observed physical condition; unknown stays unknown."
                              },
                              "printingId": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "maxLength": 120
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Exact printing id, or null if unresolved."
                              },
                              "collectorNumber": {
                                "type": "string",
                                "maxLength": 200,
                                "minLength": 1,
                                "description": "Collector number."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Resolved physical printing details, or null when unidentified."
                      },
                      "marketValue": {
                        "anyOf": [
                          {
                            "type": "object",
                            "required": [
                              "amountUsd",
                              "source",
                              "observedAt",
                              "quoteCondition",
                              "quoteFinish",
                              "referenceId"
                            ],
                            "properties": {
                              "source": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "maxLength": 200,
                                    "minLength": 1
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Quote source or null when unknown."
                              },
                              "amountUsd": {
                                "anyOf": [
                                  {
                                    "type": "number",
                                    "maximum": 10000000,
                                    "minimum": 0,
                                    "multipleOf": 0.01
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "USD market mark or null when unknown."
                              },
                              "observedAt": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "date-time",
                                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
                                    "maxLength": 30
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Quote observation time or null when unknown."
                              },
                              "quoteFinish": {
                                "anyOf": [
                                  {
                                    "enum": [
                                      "nonfoil",
                                      "foil",
                                      "etched",
                                      "unknown"
                                    ],
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Finish the quote represents, separate from observed card finish."
                              },
                              "referenceId": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "maxLength": 200
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Source reference, if available."
                              },
                              "quoteCondition": {
                                "anyOf": [
                                  {
                                    "enum": [
                                      "near_mint",
                                      "lightly_played",
                                      "moderately_played",
                                      "heavily_played",
                                      "damaged",
                                      "unknown"
                                    ],
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "Condition the quote represents, separate from observed card condition."
                              }
                            },
                            "additionalProperties": false
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Exact market evidence, or null when no supported quote exists."
                      },
                      "acceptedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Buyer-accepted units in this report."
                      },
                      "receivedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Cumulative physically received count."
                      },
                      "rejectedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Rejected units in this report."
                      },
                      "unresolvedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Units whose identity, condition, count or status remains unresolved."
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 50,
                  "minItems": 1,
                  "description": "One line per agreed category; quantities account for every received unit."
                },
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Short evidence note for the inspection and report."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "seller_response",
              "description": "Record seller acceptance or rejection of one exact estimate report."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "evaluationVersion",
                "decision",
                "evidence"
              ],
              "properties": {
                "decision": {
                  "enum": [
                    "accepted",
                    "rejected"
                  ],
                  "type": "string",
                  "description": "Seller's response to that exact report."
                },
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Evidence of seller's response."
                },
                "evaluationVersion": {
                  "type": "integer",
                  "maximum": 9007199254740991,
                  "minimum": 1,
                  "description": "Exact evaluation version answered by seller."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "payment_observed",
              "description": "Record an external transfer already observed; never sends money."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "direction",
                "amountUsd",
                "method",
                "payerRole",
                "payeeRole",
                "externalReference",
                "provenance",
                "evidence"
              ],
              "properties": {
                "method": {
                  "enum": [
                    "cash",
                    "paypal",
                    "venmo",
                    "zelle",
                    "check",
                    "store_credit",
                    "other"
                  ],
                  "type": "string",
                  "description": "Reported transfer method."
                },
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Short evidence note; it does not prove bank settlement."
                },
                "amountUsd": {
                  "type": "number",
                  "maximum": 10000000,
                  "minimum": 0.01,
                  "multipleOf": 0.01,
                  "description": "Positive whole-cent USD transfer amount already observed."
                },
                "direction": {
                  "enum": [
                    "payment",
                    "refund"
                  ],
                  "type": "string",
                  "description": "Already-observed external payment or refund direction."
                },
                "payeeRole": {
                  "enum": [
                    "buyer",
                    "seller",
                    "third_party"
                  ],
                  "type": "string",
                  "description": "Reported payee role; third-party transfers are currently rejected."
                },
                "payerRole": {
                  "enum": [
                    "buyer",
                    "seller",
                    "third_party"
                  ],
                  "type": "string",
                  "description": "Reported payer role; third-party transfers are currently rejected."
                },
                "provenance": {
                  "enum": [
                    "customer_reported",
                    "agent_observed"
                  ],
                  "type": "string",
                  "description": "Whether the transfer was customer-reported or agent-observed."
                },
                "externalReference": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 200
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "Transfer reference for deduplication, or null when unavailable."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "payment_correction",
              "description": "Replace or void a mistaken reported payment; void is not a refund."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "direction",
                    "amountUsd",
                    "method",
                    "payerRole",
                    "payeeRole",
                    "externalReference",
                    "provenance",
                    "evidence",
                    "action",
                    "paymentSubmissionId",
                    "correctionReason"
                  ],
                  "properties": {
                    "action": {
                      "type": "string",
                      "const": "replace",
                      "description": "Replace details for the same external transfer."
                    },
                    "method": {
                      "enum": [
                        "cash",
                        "paypal",
                        "venmo",
                        "zelle",
                        "check",
                        "store_credit",
                        "other"
                      ],
                      "type": "string",
                      "description": "Reported transfer method."
                    },
                    "evidence": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Short evidence note; it does not prove bank settlement."
                    },
                    "amountUsd": {
                      "type": "number",
                      "maximum": 10000000,
                      "minimum": 0.01,
                      "multipleOf": 0.01,
                      "description": "Positive whole-cent USD transfer amount already observed."
                    },
                    "direction": {
                      "enum": [
                        "payment",
                        "refund"
                      ],
                      "type": "string",
                      "description": "Already-observed external payment or refund direction."
                    },
                    "payeeRole": {
                      "enum": [
                        "buyer",
                        "seller",
                        "third_party"
                      ],
                      "type": "string",
                      "description": "Reported payee role; third-party transfers are currently rejected."
                    },
                    "payerRole": {
                      "enum": [
                        "buyer",
                        "seller",
                        "third_party"
                      ],
                      "type": "string",
                      "description": "Reported payer role; third-party transfers are currently rejected."
                    },
                    "provenance": {
                      "enum": [
                        "customer_reported",
                        "agent_observed"
                      ],
                      "type": "string",
                      "description": "Whether the transfer was customer-reported or agent-observed."
                    },
                    "correctionReason": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Why the earlier observation was incorrect."
                    },
                    "externalReference": {
                      "anyOf": [
                        {
                          "type": "string",
                          "maxLength": 200
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Transfer reference for deduplication, or null when unavailable."
                    },
                    "paymentSubmissionId": {
                      "type": "string",
                      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
                      "description": "Submission id of the prior payment observation."
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "action",
                    "paymentSubmissionId",
                    "correctionReason",
                    "evidence"
                  ],
                  "properties": {
                    "action": {
                      "type": "string",
                      "const": "void",
                      "description": "Void a false/duplicate observation without creating a refund."
                    },
                    "evidence": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Evidence supporting this void."
                    },
                    "correctionReason": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Why the earlier observation was incorrect."
                    },
                    "paymentSubmissionId": {
                      "type": "string",
                      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
                      "description": "Submission id of the prior payment observation."
                    }
                  },
                  "additionalProperties": false
                }
              ]
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "goods_disposition",
              "description": "Record physical units acquired, returned, or still unresolved."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "categories"
              ],
              "properties": {
                "categories": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "category",
                      "acquiredQuantity",
                      "returnedQuantity",
                      "unresolvedQuantity",
                      "titleEvidence",
                      "releaseEvidence",
                      "unresolvedEvidence"
                    ],
                    "properties": {
                      "category": {
                        "type": "string",
                        "maxLength": 80,
                        "minLength": 1,
                        "description": "Agreed physical category."
                      },
                      "titleEvidence": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 200,
                            "minLength": 1
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Evidence title transferred for acquired units; null otherwise."
                      },
                      "releaseEvidence": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 200,
                            "minLength": 1
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Evidence goods were released to seller; null otherwise."
                      },
                      "acquiredQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Units for which title was acquired."
                      },
                      "returnedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Units physically released back to seller."
                      },
                      "unresolvedEvidence": {
                        "anyOf": [
                          {
                            "type": "string",
                            "maxLength": 200,
                            "minLength": 1
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Evidence for unresolved disposition; null otherwise."
                      },
                      "unresolvedQuantity": {
                        "type": "integer",
                        "maximum": 100000,
                        "minimum": 0,
                        "description": "Units whose location/title remains unresolved."
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 50,
                  "minItems": 1,
                  "description": "One line per report category."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "dispute",
              "description": "Open or resolve a named reconciliation dispute."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "oneOf": [
                {
                  "type": "object",
                  "required": [
                    "action",
                    "disputeId",
                    "amountUsd",
                    "evidence"
                  ],
                  "properties": {
                    "action": {
                      "type": "string",
                      "const": "open",
                      "description": "Open a dispute."
                    },
                    "evidence": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Evidence for the dispute."
                    },
                    "amountUsd": {
                      "anyOf": [
                        {
                          "type": "number",
                          "maximum": 10000000,
                          "minimum": 0,
                          "multipleOf": 0.01
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Disputed USD amount, or null when unknown."
                    },
                    "disputeId": {
                      "type": "string",
                      "maxLength": 80,
                      "minLength": 1,
                      "description": "Unique dispute id."
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "action",
                    "disputeId",
                    "resolution",
                    "evidence"
                  ],
                  "properties": {
                    "action": {
                      "type": "string",
                      "const": "resolve",
                      "description": "Resolve an existing dispute."
                    },
                    "evidence": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "Evidence for resolution."
                    },
                    "disputeId": {
                      "type": "string",
                      "maxLength": 80,
                      "minLength": 1,
                      "description": "Existing dispute id."
                    },
                    "resolution": {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1,
                      "description": "How the dispute was resolved."
                    }
                  },
                  "additionalProperties": false
                }
              ]
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "close",
              "description": "Close only after all counts, goods, payments/refunds and disputes reconcile."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "evidence"
              ],
              "properties": {
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Evidence the submitted deal facts reconcile."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "dealId",
            "expectedRevision",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "reopen",
              "description": "Reopen a closed deal to record late corrections or disputes."
            },
            "dealId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Deal id returned by the open command."
            },
            "payload": {
              "type": "object",
              "required": [
                "reason",
                "evidence"
              ],
              "properties": {
                "reason": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "Why the closed deal must be reopened."
                },
                "evidence": {
                  "type": "string",
                  "maxLength": 200,
                  "minLength": 1,
                  "description": "New evidence requiring recovery."
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
              "maxLength": 30,
              "description": "When the agreement or evidence was observed."
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
              "description": "Fresh idempotency ULID; reuse this exact id and payload after an uncertain write."
            },
            "expectedRevision": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1,
              "description": "Current revision from spellbook_collection_buying_get; stale revisions are rejected."
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "One lifecycle command with a fresh submissionId and occurredAt. After open, supply dealId and expectedRevision."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller-owned workspace to record this deal in. Required."
    }
  },
  "additionalProperties": false
}

spellbook_collection_receipt

Read one receipt for the cards a workspace holds: total copies, distinct printings, printings held two or more times, copies with a market price and their market USD total, copies and market USD in each value band, copies and market USD at one dollar and up, the market USD of the most valuable copies up to topUnitsCap, and the top rows by market value with card name, set, collector number, finish, condition, copies, unit market and the Intelligent Pricing TCGplayer ask when one was computed. Call it to answer what a collection holds and what it is worth in one read; it works for a free collection-only workspace and for a store. Call spellbook_inventory_holdings next for every row, or spellbook_buylist_compare for per-destination nets. It reports facts; it does not rank, score or pick what to sell.

read-only

Argument	Type	Description
workspaceId*	string	The workspace whose held cards to total, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose held cards to total, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_credit_conversion_candidates

Read CK credit-funded sealed acquisition candidates ranked by opening EV. Cash/credit opening multiples do NOT rank intact sealed resale cash profit. Credit is restricted purchasing power.

read-only

Argument	Type	Description
boxType	string	Restrict candidates to one box type. Defaults to all, covering every type.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "boxType": {
      "enum": [
        "all",
        "play",
        "draft",
        "jumpstart",
        "commander",
        "precon"
      ],
      "type": "string",
      "default": "all",
      "description": "Restrict candidates to one box type. Defaults to all, covering every type."
    }
  },
  "additionalProperties": false
}

spellbook_credit_resale_assessment

Assess up to ten exact sealed product lines as a CK-credit-funded intact resale scenario. Supply starting credit and explicit cost assumptions; omit unknown costs. EV judgment is permitted. Returns labeled cash estimates, credit allocation, capacity and missing evidence. Research only, no purchase.

read-only

Argument	Type	Description
costs*	object	Explicit cost assumptions for the resale scenario. Every field is optional; omit any cost that is unknown rather than guessing zero.
lines*	array	Up to 10 exact sealed product lines to assess. Required, at least one.
exitChannel*	string	Name of the channel the intact resale would exit through. Required, up to 30 characters.
startingCreditUsd*	number	Card Kingdom store credit available to spend in this scenario, in USD. Required.
maxSnapshotAgeHours*	number	Maximum age in hours of price snapshots this assessment may use. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "startingCreditUsd",
    "exitChannel",
    "maxSnapshotAgeHours",
    "lines",
    "costs"
  ],
  "properties": {
    "costs": {
      "type": "object",
      "properties": {
        "orderCount": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1
            }
          },
          "description": "Assumed number of orders with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "parcelCount": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "integer",
              "maximum": 100000,
              "minimum": 1
            }
          },
          "description": "Assumed number of parcels with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "checkoutTaxUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed checkout tax in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "checkoutPayment": {
          "enum": [
            "cash",
            "credit"
          ],
          "type": "string",
          "description": "Whether checkout was paid in cash or credit. Omit if unknown."
        },
        "checkoutOtherUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed other checkout costs in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "combinedFeeRatePct": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 100,
              "minimum": 0
            }
          },
          "description": "Assumed combined marketplace fee rate as a percent with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "salesTaxFeeBaseUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed sales-tax fee base in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "checkoutShippingUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed checkout shipping cost in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "fixedFeePerOrderUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed fixed fee per order in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "postagePerParcelUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed postage per parcel in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "otherExitCashCostsUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed other exit cash costs in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "packagingPerParcelUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed packaging cost per parcel in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        },
        "buyerShippingCollectedUsd": {
          "type": "object",
          "required": [
            "value",
            "basis"
          ],
          "properties": {
            "basis": {
              "type": "string",
              "maxLength": 500,
              "minLength": 1
            },
            "value": {
              "type": "number",
              "maximum": 1000000,
              "minimum": 0,
              "multipleOf": 0.01
            }
          },
          "description": "Assumed shipping collected from the resale buyer in USD with its basis. Omit if unknown.",
          "additionalProperties": false
        }
      },
      "description": "Explicit cost assumptions for the resale scenario. Every field is optional; omit any cost that is unknown rather than guessing zero.",
      "additionalProperties": false
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "tcgProductId",
          "expectedBoxType",
          "quantity"
        ],
        "properties": {
          "quantity": {
            "type": "integer",
            "maximum": 10000,
            "minimum": 1,
            "description": "Number of units of this line in the scenario. Required."
          },
          "tcgProductId": {
            "type": "string",
            "pattern": "^\\d{1,12}$",
            "description": "Exact TCGplayer product id for this sealed product line, digits only. Required."
          },
          "expectedBoxType": {
            "enum": [
              "play",
              "draft",
              "jumpstart",
              "commander",
              "precon"
            ],
            "type": "string",
            "description": "The expected box type for this line. Required."
          },
          "resaleUnitPriceUsd": {
            "type": "object",
            "required": [
              "value",
              "basis"
            ],
            "properties": {
              "basis": {
                "type": "string",
                "maxLength": 500,
                "minLength": 1
              },
              "value": {
                "type": "number",
                "maximum": 1000000,
                "minimum": 0,
                "multipleOf": 0.01
              }
            },
            "description": "Assumed per-unit intact resale price in USD with its basis. Omit to leave resale price unassumed.",
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "maxItems": 10,
      "minItems": 1,
      "description": "Up to 10 exact sealed product lines to assess. Required, at least one."
    },
    "exitChannel": {
      "type": "string",
      "maxLength": 30,
      "minLength": 1,
      "description": "Name of the channel the intact resale would exit through. Required, up to 30 characters."
    },
    "startingCreditUsd": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 0,
      "multipleOf": 0.01,
      "description": "Card Kingdom store credit available to spend in this scenario, in USD. Required."
    },
    "maxSnapshotAgeHours": {
      "type": "number",
      "maximum": 8760,
      "description": "Maximum age in hours of price snapshots this assessment may use. Required.",
      "exclusiveMinimum": 0
    }
  },
  "additionalProperties": false
}

spellbook_customer_evidence_get

Read one private immutable evidence receipt from the selected workspace. Returned observations and source fields remain submitted evidence.

read-only

Argument	Type	Description
receiptId*	string	The receipt's receiptId from the record response, or the submissionId you chose when recording it. Either one resolves the same receipt inside the workspace. Required.
workspaceId*	string	The workspace the receipt belongs to. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "receiptId"
  ],
  "properties": {
    "receiptId": {
      "type": "string",
      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
      "description": "The receipt's receiptId from the record response, or the submissionId you chose when recording it. Either one resolves the same receipt inside the workspace. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the receipt belongs to. Required."
    }
  },
  "additionalProperties": false
}

spellbook_customer_evidence_list

List a bounded page of private evidence receipts from the selected workspace, optionally filtered by receipt kind, parent, or item ID.

read-only

Argument	Type	Description
kind	string	Restrict the list to one receipt kind. Omit to include every kind.
limit	integer	Maximum receipts to return, 1 to 50. Omit for the default of 20.
cursor	string	Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page.
itemId	string	Restrict the list to receipts referencing this exact item id. Omit for no item filter.
workspaceId*	string	The workspace to list receipts from. Required.
parentReceiptId	string	Restrict the list to receipts linked to this parent receipt's receiptId from the record response. Omit for no parent filter.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "kind": {
      "enum": [
        "consideration",
        "work_observation",
        "realized_outcome"
      ],
      "type": "string",
      "description": "Restrict the list to one receipt kind. Omit to include every kind."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum receipts to return, 1 to 50. Omit for the default of 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "itemId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Restrict the list to receipts referencing this exact item id. Omit for no item filter."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to list receipts from. Required."
    },
    "parentReceiptId": {
      "type": "string",
      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
      "description": "Restrict the list to receipts linked to this parent receipt's receiptId from the record response. Omit for no parent filter."
    }
  },
  "additionalProperties": false
}

spellbook_customer_evidence_record

Append one immutable consideration, realized outcome, or work observation to the selected workspace. A receipt proves storage only. It does not verify source providers, inspected card truth, profit, or completed work.

Argument	Type	Description
request*	any	The evidence envelope: a submissionId, occurredAt, a kind (realized_outcome, consideration or work_observation), and that kind's payload. Required.
workspaceId*	string	The workspace to append this evidence to. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "request"
  ],
  "properties": {
    "request": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "realized_outcome"
            },
            "payload": {
              "type": "object",
              "required": [
                "parentReceiptId",
                "candidateId",
                "stage",
                "provenance",
                "summary",
                "purchasedAt",
                "receivedAt",
                "soldAt",
                "settledAt",
                "quantityPurchased",
                "quantityReceived",
                "quantitySold",
                "quantityWrittenOff",
                "receivedDescription",
                "paidUsd",
                "refundUsd",
                "saleGrossUsd",
                "exitFeesUsd",
                "exitShippingUsd",
                "orderReference",
                "benchmark"
              ],
              "properties": {
                "stage": {
                  "enum": [
                    "purchased",
                    "received",
                    "closed",
                    "abandoned"
                  ],
                  "type": "string"
                },
                "soldAt": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "paidUsd": {
                  "type": "number",
                  "maximum": 1000000000,
                  "minimum": 0,
                  "multipleOf": 0.01
                },
                "summary": {
                  "type": "string",
                  "maxLength": 500,
                  "minLength": 1
                },
                "benchmark": {
                  "anyOf": [
                    {
                      "type": "object",
                      "required": [
                        "method",
                        "marks"
                      ],
                      "properties": {
                        "marks": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "id",
                              "priceUsd",
                              "observedAt",
                              "source"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "maxLength": 100,
                                "minLength": 1
                              },
                              "source": {
                                "type": "string",
                                "maxLength": 500,
                                "minLength": 1
                              },
                              "priceUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "observedAt": {
                                "type": "string",
                                "format": "date-time",
                                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                              }
                            },
                            "additionalProperties": false
                          },
                          "maxItems": 200,
                          "minItems": 1
                        },
                        "method": {
                          "type": "string",
                          "const": "equal_weight_fixed_printing_basket"
                        }
                      },
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "refundUsd": {
                  "type": "number",
                  "maximum": 1000000000,
                  "minimum": 0,
                  "multipleOf": 0.01
                },
                "settledAt": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "provenance": {
                  "enum": [
                    "customer_reported",
                    "agent_observed"
                  ],
                  "type": "string"
                },
                "receivedAt": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "candidateId": {
                  "type": "string",
                  "maxLength": 100,
                  "minLength": 1
                },
                "exitFeesUsd": {
                  "anyOf": [
                    {
                      "type": "number",
                      "maximum": 1000000000,
                      "minimum": 0,
                      "multipleOf": 0.01
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "purchasedAt": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "quantitySold": {
                  "type": "integer",
                  "maximum": 100000,
                  "minimum": 0
                },
                "saleGrossUsd": {
                  "anyOf": [
                    {
                      "type": "number",
                      "maximum": 1000000000,
                      "minimum": 0,
                      "multipleOf": 0.01
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "orderReference": {
                  "anyOf": [
                    {
                      "type": "string",
                      "maxLength": 200,
                      "minLength": 1
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "exitShippingUsd": {
                  "anyOf": [
                    {
                      "type": "number",
                      "maximum": 1000000000,
                      "minimum": 0,
                      "multipleOf": 0.01
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "parentReceiptId": {
                  "type": "string",
                  "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
                  "description": "The parent consideration's receiptId from the record response, or the submissionId you chose when recording it. Either one resolves the same receipt inside the workspace; the stored link is always the receiptId. Required."
                },
                "quantityReceived": {
                  "type": "integer",
                  "maximum": 100000,
                  "minimum": 0
                },
                "quantityPurchased": {
                  "type": "integer",
                  "maximum": 100000,
                  "minimum": 0
                },
                "quantityWrittenOff": {
                  "type": "integer",
                  "maximum": 100000,
                  "minimum": 0
                },
                "receivedDescription": {
                  "type": "string",
                  "maxLength": 500,
                  "minLength": 1
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "consideration"
            },
            "payload": {
              "type": "object",
              "required": [
                "preferences",
                "coverage",
                "sources",
                "resources",
                "candidates"
              ],
              "properties": {
                "sources": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "source",
                      "observedAt"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1
                      },
                      "source": {
                        "type": "string",
                        "maxLength": 500,
                        "minLength": 1
                      },
                      "observedAt": {
                        "type": "string",
                        "format": "date-time",
                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                      },
                      "snapshotId": {
                        "type": "string",
                        "maxLength": 200,
                        "minLength": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 20
                },
                "coverage": {
                  "type": "object",
                  "required": [
                    "kind",
                    "searched",
                    "limitations"
                  ],
                  "properties": {
                    "kind": {
                      "type": "string",
                      "const": "agent_observed"
                    },
                    "searched": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "maxLength": 500,
                        "minLength": 1
                      },
                      "maxItems": 25
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "maxLength": 500,
                        "minLength": 1
                      },
                      "maxItems": 25
                    }
                  },
                  "additionalProperties": false
                },
                "benchmark": {
                  "type": "object",
                  "required": [
                    "method",
                    "marks"
                  ],
                  "properties": {
                    "marks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "priceUsd",
                          "observedAt",
                          "source"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "maxLength": 100,
                            "minLength": 1
                          },
                          "source": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "priceUsd": {
                            "type": "number",
                            "maximum": 1000000,
                            "minimum": 0,
                            "multipleOf": 0.01
                          },
                          "observedAt": {
                            "type": "string",
                            "format": "date-time",
                            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                          }
                        },
                        "additionalProperties": false
                      },
                      "maxItems": 200,
                      "minItems": 1
                    },
                    "method": {
                      "type": "string",
                      "const": "equal_weight_fixed_printing_basket"
                    }
                  },
                  "additionalProperties": false
                },
                "resources": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "kind",
                      "capacity",
                      "unit"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1
                      },
                      "kind": {
                        "enum": [
                          "capital",
                          "stock"
                        ],
                        "type": "string"
                      },
                      "unit": {
                        "enum": [
                          "usd",
                          "units"
                        ],
                        "type": "string"
                      },
                      "capacity": {
                        "anyOf": [
                          {
                            "type": "number",
                            "maximum": 1000000000,
                            "minimum": 0
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "sourceId": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 20
                },
                "candidates": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "label",
                      "status",
                      "rationale",
                      "sourceIds",
                      "exclusiveGroupIds",
                      "resourceUses",
                      "effort",
                      "risk",
                      "holdingDays",
                      "economics",
                      "unknowns",
                      "actualRecordRefs"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1
                      },
                      "risk": {
                        "type": "object",
                        "required": [
                          "condition",
                          "price",
                          "liquidity",
                          "basis"
                        ],
                        "properties": {
                          "basis": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "price": {
                            "enum": [
                              "low",
                              "medium",
                              "high",
                              "unknown"
                            ],
                            "type": "string"
                          },
                          "condition": {
                            "enum": [
                              "low",
                              "medium",
                              "high",
                              "unknown"
                            ],
                            "type": "string"
                          },
                          "liquidity": {
                            "enum": [
                              "low",
                              "medium",
                              "high",
                              "unknown"
                            ],
                            "type": "string"
                          }
                        },
                        "additionalProperties": false
                      },
                      "label": {
                        "type": "string",
                        "maxLength": 500,
                        "minLength": 1
                      },
                      "effort": {
                        "type": "object",
                        "required": [
                          "activeMinutes",
                          "parcels",
                          "cardsHandled",
                          "basis"
                        ],
                        "properties": {
                          "basis": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "parcels": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "cardsHandled": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "activeMinutes": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": false
                      },
                      "status": {
                        "enum": [
                          "chosen",
                          "declined",
                          "unknown"
                        ],
                        "type": "string"
                      },
                      "unknowns": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "maxLength": 500,
                          "minLength": 1
                        },
                        "maxItems": 25
                      },
                      "buyTarget": {
                        "type": "object",
                        "required": [
                          "id",
                          "label",
                          "scryfallId",
                          "tcgProductId",
                          "finish",
                          "condition",
                          "language",
                          "buy",
                          "exit",
                          "expectedNetUsd",
                          "status",
                          "reasons",
                          "thesisKillers",
                          "stopRules",
                          "thin"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "buy": {
                            "type": "object",
                            "required": [
                              "venue",
                              "sellerName",
                              "listingId",
                              "url",
                              "unitPriceUsd",
                              "shippingPerOrderUsd",
                              "allInUnitUsd",
                              "availableQuantity",
                              "priceCeilingUsd",
                              "allInCeilingUsd",
                              "quantity",
                              "quantityCap",
                              "freshness"
                            ],
                            "properties": {
                              "url": {
                                "type": "string",
                                "format": "uri"
                              },
                              "venue": {
                                "type": "string",
                                "const": "tcgplayer"
                              },
                              "quantity": {
                                "type": "integer",
                                "maximum": 9007199254740991,
                                "minimum": 0
                              },
                              "freshness": {
                                "type": "object",
                                "required": [
                                  "observedAt",
                                  "ageHours"
                                ],
                                "properties": {
                                  "ageHours": {
                                    "anyOf": [
                                      {
                                        "type": "number"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "observedAt": {
                                    "anyOf": [
                                      {
                                        "type": "string"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                },
                                "additionalProperties": false
                              },
                              "listingId": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "maxLength": 500,
                                    "minLength": 1
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "sellerName": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "maxLength": 500,
                                    "minLength": 1
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "quantityCap": {
                                "type": "integer",
                                "maximum": 9007199254740991,
                                "minimum": 0
                              },
                              "allInUnitUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "unitPriceUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "allInCeilingUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "priceCeilingUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "availableQuantity": {
                                "type": "integer",
                                "maximum": 9007199254740991,
                                "minimum": 0
                              },
                              "shippingPerOrderUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              }
                            },
                            "additionalProperties": false
                          },
                          "exit": {
                            "type": "object",
                            "required": [
                              "venue",
                              "url",
                              "productName",
                              "gradeScenario",
                              "expectedUnitUsd",
                              "nmUnitUsd",
                              "exUnitUsd",
                              "feesAndDeliveryPerUnitUsd",
                              "expectedNetUnitUsd",
                              "quantityBuying",
                              "source",
                              "freshness"
                            ],
                            "properties": {
                              "url": {
                                "type": "string",
                                "format": "uri"
                              },
                              "venue": {
                                "type": "string",
                                "const": "cardkingdom"
                              },
                              "source": {
                                "type": "string",
                                "maxLength": 500,
                                "minLength": 1
                              },
                              "exUnitUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "freshness": {
                                "type": "object",
                                "required": [
                                  "observedAt",
                                  "ageHours"
                                ],
                                "properties": {
                                  "ageHours": {
                                    "anyOf": [
                                      {
                                        "type": "number"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "observedAt": {
                                    "anyOf": [
                                      {
                                        "type": "string"
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                },
                                "additionalProperties": false
                              },
                              "nmUnitUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "productName": {
                                "type": "string",
                                "maxLength": 500,
                                "minLength": 1
                              },
                              "gradeScenario": {
                                "enum": [
                                  "NM",
                                  "EX"
                                ],
                                "type": "string"
                              },
                              "quantityBuying": {
                                "type": "integer",
                                "maximum": 9007199254740991,
                                "minimum": 0
                              },
                              "expectedUnitUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              },
                              "expectedNetUnitUsd": {
                                "type": "number"
                              },
                              "feesAndDeliveryPerUnitUsd": {
                                "type": "number",
                                "maximum": 1000000,
                                "minimum": 0,
                                "multipleOf": 0.01
                              }
                            },
                            "additionalProperties": false
                          },
                          "name": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "thin": {
                            "type": "boolean"
                          },
                          "label": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "finish": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "status": {
                            "enum": [
                              "candidate",
                              "rejected"
                            ],
                            "type": "string"
                          },
                          "reasons": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 500,
                              "minLength": 1
                            }
                          },
                          "setCode": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "setName": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "language": {
                            "type": "string",
                            "const": "English"
                          },
                          "condition": {
                            "type": "string",
                            "const": "NM"
                          },
                          "stopRules": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 500,
                              "minLength": 1
                            }
                          },
                          "scryfallId": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "tcgProductId": {
                            "type": "string",
                            "maxLength": 500,
                            "minLength": 1
                          },
                          "thesisKillers": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "maxLength": 500,
                              "minLength": 1
                            }
                          },
                          "expectedNetUsd": {
                            "type": "number"
                          },
                          "collectorNumber": {
                            "anyOf": [
                              {
                                "type": "string",
                                "maxLength": 500,
                                "minLength": 1
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": false
                      },
                      "economics": {
                        "type": "object",
                        "required": [
                          "cashOutUsd",
                          "cashInUsd",
                          "creditSpentUsd",
                          "creditReceivedUsd",
                          "inventoryMarketUsd",
                          "basis"
                        ],
                        "properties": {
                          "basis": {
                            "enum": [
                              "quote",
                              "estimate",
                              "unknown"
                            ],
                            "type": "string"
                          },
                          "cashInUsd": {
                            "anyOf": [
                              {
                                "type": "number",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "cashOutUsd": {
                            "anyOf": [
                              {
                                "type": "number",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "creditSpentUsd": {
                            "anyOf": [
                              {
                                "type": "number",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "creditReceivedUsd": {
                            "anyOf": [
                              {
                                "type": "number",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "inventoryMarketUsd": {
                            "anyOf": [
                              {
                                "type": "number",
                                "maximum": 1000000000,
                                "minimum": 0
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "additionalProperties": false
                      },
                      "rationale": {
                        "type": "string",
                        "maxLength": 500,
                        "minLength": 1
                      },
                      "sourceIds": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "maxLength": 100,
                          "minLength": 1
                        },
                        "maxItems": 25
                      },
                      "holdingDays": {
                        "anyOf": [
                          {
                            "type": "integer",
                            "maximum": 1000000000,
                            "minimum": 0
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "resourceUses": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "resourceId",
                            "amount"
                          ],
                          "properties": {
                            "amount": {
                              "anyOf": [
                                {
                                  "type": "number",
                                  "maximum": 1000000000,
                                  "minimum": 0
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "resourceId": {
                              "type": "string",
                              "maxLength": 100,
                              "minLength": 1
                            }
                          },
                          "additionalProperties": false
                        },
                        "maxItems": 25
                      },
                      "actualRecordRefs": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "required": [
                            "kind",
                            "id"
                          ],
                          "properties": {
                            "id": {
                              "type": "string",
                              "maxLength": 200,
                              "minLength": 1
                            },
                            "kind": {
                              "enum": [
                                "acquisition",
                                "disposition",
                                "earnings"
                              ],
                              "type": "string"
                            }
                          },
                          "additionalProperties": false
                        },
                        "maxItems": 25
                      },
                      "exclusiveGroupIds": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "maxLength": 100,
                          "minLength": 1
                        },
                        "maxItems": 25
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 20,
                  "minItems": 1
                },
                "preferences": {
                  "type": "object",
                  "required": [
                    "version",
                    "asOf",
                    "capitalBudgetUsd",
                    "maxActiveMinutesPerWeek",
                    "maxParcelsPerWeek",
                    "riskTolerance",
                    "notes"
                  ],
                  "properties": {
                    "asOf": {
                      "type": "string",
                      "format": "date-time",
                      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                    },
                    "notes": {
                      "type": "string",
                      "maxLength": 500,
                      "minLength": 1
                    },
                    "version": {
                      "type": "string",
                      "maxLength": 100,
                      "minLength": 1
                    },
                    "riskTolerance": {
                      "enum": [
                        "low",
                        "medium",
                        "high",
                        "unknown"
                      ],
                      "type": "string"
                    },
                    "capitalBudgetUsd": {
                      "anyOf": [
                        {
                          "type": "number",
                          "maximum": 1000000000,
                          "minimum": 0
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "maxParcelsPerWeek": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "maximum": 1000000000,
                          "minimum": 0
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "maxActiveMinutesPerWeek": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "maximum": 1000000000,
                          "minimum": 0
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "submissionId",
            "occurredAt",
            "kind",
            "payload"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "const": "work_observation"
            },
            "payload": {
              "type": "object",
              "required": [
                "itemIds",
                "observation",
                "provenance",
                "summary",
                "actualRecordRefs"
              ],
              "properties": {
                "binId": {
                  "type": "string",
                  "maxLength": 120,
                  "minLength": 1
                },
                "itemIds": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 200,
                    "minLength": 1
                  },
                  "maxItems": 25
                },
                "summary": {
                  "type": "string",
                  "maxLength": 500,
                  "minLength": 1
                },
                "provenance": {
                  "enum": [
                    "customer_reported",
                    "agent_observed"
                  ],
                  "type": "string"
                },
                "observation": {
                  "enum": [
                    "reported_done",
                    "placement_reported",
                    "api_save_failed",
                    "location_readback"
                  ],
                  "type": "string"
                },
                "parentReceiptId": {
                  "type": "string",
                  "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
                  "description": "The parent consideration's receiptId from the record response, or the submissionId you chose when recording it. Either one resolves the same receipt inside the workspace; the stored link is always the receiptId. Omit when the work links to no consideration."
                },
                "actualRecordRefs": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "kind",
                      "id"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "maxLength": 200,
                        "minLength": 1
                      },
                      "kind": {
                        "enum": [
                          "acquisition",
                          "disposition",
                          "earnings"
                        ],
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  "maxItems": 25
                }
              },
              "additionalProperties": false
            },
            "occurredAt": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            "submissionId": {
              "type": "string",
              "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "The evidence envelope: a submissionId, occurredAt, a kind (realized_outcome, consideration or work_observation), and that kind's payload. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to append this evidence to. Required."
    }
  },
  "additionalProperties": false
}

spellbook_deck_contents

Read one authenticated customer's exact owned and draft card contents for a deck. The response preserves game identity, entry ids, matched catalog identity, quantities, membership recovery count and Pokemon readiness checks. It reports facts only and does not edit a deck or infer missing cards.

read-only

Argument	Type	Description
deckId*	string	The exact deck id returned by the deck workflow. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "deckId"
  ],
  "properties": {
    "deckId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]+$",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact deck id returned by the deck workflow. Required."
    }
  },
  "additionalProperties": false
}

spellbook_deck_import_limitless

Import one player's Pokemon decklist from one fixed Limitless tournament standings record into the seller's workspace. The workspace owner chooses the event, player, format and idempotency key; retries with the same key replay the first result or report an in-progress import. The tool does not accept URLs or credentials and returns source identity, matched and unmatched counts, and the imported deck.

Argument	Type	Description
name	string	Optional deck name.
format	string	Deck format. Defaults to Standard.
eventId*	string	The Limitless tournament event id. Required.
playerId*	string	The exact player name or id as shown by the selected event. Required.
workspaceId*	string	The workspace to import into. The caller must be its owner. Required.
idempotencyKey*	string	A caller-generated retry key. Reuse it unchanged after an uncertain result. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "eventId",
    "playerId",
    "idempotencyKey"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Optional deck name."
    },
    "format": {
      "enum": [
        "Standard",
        "Expanded",
        "Unlimited"
      ],
      "type": "string",
      "default": "Standard",
      "description": "Deck format. Defaults to Standard."
    },
    "eventId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The Limitless tournament event id. Required."
    },
    "playerId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact player name or id as shown by the selected event. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to import into. The caller must be its owner. Required."
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A caller-generated retry key. Reuse it unchanged after an uncertain result. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_automation_set

Set one workspace's eBay automation mode, which decides whether SpellBook lists and reprices on eBay by itself, whether that automation lists basic lands, and how many copies one listing may carry. This changes public eBay behavior for the workspace, only the workspace owner may call it, and the agent sets a mode only after the seller chose one. The modes: manual: Nothing lists or reprices on eBay automatically; you publish from the eBay preview when you choose. auto_list: New eligible inventory lists on eBay automatically at your saved eBay pricing strategy's prices, and existing eBay listings are never repriced automatically. full: New inventory lists on eBay automatically, and existing eBay listings reprice from your saved eBay pricing strategy. With variation packages on (the default), new inventory groups into one listing per set with each card as a variation; with them off, each card lists on its own.

destructive

Argument	Type	Description
mode	string	The mode the seller chose: manual, auto_list, or full. Send mode, basicLandsEnabled, maxQuantityPerListing, or any mix.
workspaceId*	string	The workspace whose eBay automation mode to set. The caller must own it. Required.
basicLandsEnabled	boolean	true lets auto_list and full list basic lands (Plains, Island, Swamp, Mountain, Forest, Wastes, and their Snow-Covered printings). false skips them. The saved value defaults to false.
maxQuantityPerListing	any	The most available copies one eBay listing may advertise, such as 3. null removes the cap. Omit it to keep the saved value, which defaults to null.

spellbook_ebay_combined_shipping_get

Read the caller's connected eBay combined-shipping profile and promotional shipping rule, including its provider type, amount threshold or maximum order cost, and configuration status. Call spellbook_ebay_combined_shipping_set after reviewing it. eBay checkout may still require multiple items for an amount-threshold offer; use eBay Seller Hub Shipping discounts when a minimum amount must qualify one item.

read-only

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_combined_shipping_set

Set the caller's connected eBay combined-shipping charge and optional amount-threshold offer or maximum shipping cost per order, then return Account API readback. Read spellbook_ebay_combined_shipping_get first. Configure an amount-only single-item Shipping discount separately in Seller Hub.

destructive

Argument	Type	Description
profileName	string	Seller-selected eBay rule name. Defaults to SpellBook Finance Combined Shipping.
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.
combinedDuration	string	Optional buyer accumulation window. Omit to preserve the existing eBay window; a new account without one falls back to Days_7.
eachAdditionalAmountUsd	number	Seller-selected shipping charge for each additional item in USD. Defaults to 0.
promotionalShippingRule	any	Optional shipping promotion. Use {orderAmountUsd, shippingCostUsd} for the existing amount-threshold offer or {ruleType: maximum_shipping_cost_per_order, maximumShippingCostPerOrderUsd} to cap shipping per order. Omit it to preserve the existing promotion.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "profileName": {
      "type": "string",
      "default": "SpellBook Finance Combined Shipping",
      "maxLength": 50,
      "minLength": 1,
      "description": "Seller-selected eBay rule name. Defaults to SpellBook Finance Combined Shipping."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    },
    "combinedDuration": {
      "enum": [
        "Days_1",
        "Days_3",
        "Days_4",
        "Days_5",
        "Days_7",
        "Days_30"
      ],
      "type": "string",
      "description": "Optional buyer accumulation window. Omit to preserve the existing eBay window; a new account without one falls back to Days_7."
    },
    "eachAdditionalAmountUsd": {
      "type": "number",
      "default": 0,
      "maximum": 99,
      "minimum": 0,
      "description": "Seller-selected shipping charge for each additional item in USD. Defaults to 0."
    },
    "promotionalShippingRule": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "orderAmountUsd",
            "shippingCostUsd"
          ],
          "properties": {
            "orderAmountUsd": {
              "type": "number",
              "maximum": 10000,
              "description": "Minimum order subtotal for promotional shipping in USD. Required for an amount-threshold offer.",
              "exclusiveMinimum": 0
            },
            "shippingCostUsd": {
              "type": "number",
              "maximum": 99,
              "minimum": 0,
              "description": "Shipping charged when the order reaches the amount threshold in USD; use zero for free shipping. Required for an amount-threshold offer."
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "ruleType",
            "maximumShippingCostPerOrderUsd"
          ],
          "properties": {
            "ruleType": {
              "type": "string",
              "const": "maximum_shipping_cost_per_order",
              "description": "Select a maximum total shipping cost for a combined order."
            },
            "maximumShippingCostPerOrderUsd": {
              "type": "number",
              "maximum": 99,
              "minimum": 0,
              "description": "Maximum shipping cost for the combined order in USD."
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Optional shipping promotion. Use {orderAmountUsd, shippingCostUsd} for the existing amount-threshold offer or {ruleType: maximum_shipping_cost_per_order, maximumShippingCostPerOrderUsd} to cap shipping per order. Omit it to preserve the existing promotion."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_connect_link

Get the SpellBook Finance page where the seller connects their eBay account. Call spellbook_ebay_connection_status first. Hand the seller only this one link and tell them to sign in to SpellBook Finance, press Connect eBay, then sign in at eBay and approve the connection. Once they finish, call spellbook_ebay_connection_status again. The agent never receives the eBay consent URL, a password, or a token.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_ebay_connection_status

Check whether this signed-in customer's eBay seller account is connected to SpellBook Finance. Call this before requesting a connect link and call it again after the seller approves eBay consent. It returns the stored account identity and token state plus current eBay seller-registration and selling-limit facts. If connected is false and account is null, call spellbook_ebay_connect_link. If status is revoked, fetch a fresh connect link.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_ebay_job_status

Read one eBay bulk job by the jobId returned from spellbook_ebay_publish or spellbook_ebay_reprice. Both operations queue work, so call this before telling the person a listing was created or its ask changed. State planning, pending, uploading, processing or ingesting means the job is still running: call again after about a minute. State failed carries errorMessage, and each failures row carries a per-card reason: relay that reason to the person. A job with dryRun true is a reprice preview: it changed no eBay price, and totalItems counts the listings a live run would reprice. Returns state, counts, per-card items, failures and missingFields.

read-only

Argument	Type	Description
jobId*	string	The jobId returned by spellbook_ebay_publish or spellbook_ebay_reprice. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "jobId"
  ],
  "properties": {
    "jobId": {
      "type": "string",
      "pattern": "^(?:[0-9A-HJKMNP-TV-Z]{26}|autolist-[0-9a-f]{32})$",
      "description": "The jobId returned by spellbook_ebay_publish or spellbook_ebay_reprice. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_lot_publish

Publish a player-built deck from one workspace as ONE live eBay listing in eBay's player-built decks category. You choose the cards, the title, the summary, the ask and the shipping charge. This tool never suggests a price, ranks cards or picks a deck for you. It reports, per card, how many free near-mint copies the workspace holds and, when deckFormat is set, whether Scryfall lists the card as legal in that format. ALWAYS call it once with dryRun true and show the person the preview, the per-card counts and the refusals before calling it again with dryRun false, because a live run creates a real listing a real buyer can buy. A live run returns the eBay listingId and listingUrl, or the refusals. It does not reserve the copies, and it does not know whether another channel sells them first.

destructive

Argument	Type	Description
cards*	array	The deck list, at most 100 rows and 500 cards in total. Rows that share a card name are merged. Required.
title*	string	The eBay listing title, at most 80 characters. Required.
dryRun	boolean	True previews the listing with no eBay call. False publishes for real. Defaults to true; a live run needs an explicit false.
summary*	string	A short description of the deck for the listing body, at most 1000 characters. Required.
priceUsd*	number

spellbook_ebay_order_discount_disable

Disable the caller's tracked eBay order-discount promotion after reading spellbook_ebay_order_discount_get. This ends the tracked promotion and requires agent_marketplace_publish authorization.

destructive

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_order_discount_get

Read the caller's tracked eBay order-discount promotion, including store or lot scope, quantity threshold, percentage, status and dates. workspaceId is checked for owner access; the promotion belongs to the caller's connected eBay account.

read-only

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_order_discount_set

Set a store-wide eBay order discount based on a seller-selected minimum quantity and percentage. Call spellbook_ebay_order_discount_get first; only one tracked order-discount promotion is supported, so this may replace the existing one.

destructive

Argument	Type	Description
minQuantity*	integer	Seller-selected minimum item count. Required.
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.
percentageOff*	integer	Seller-selected discount percentage. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "minQuantity",
    "percentageOff"
  ],
  "properties": {
    "minQuantity": {
      "type": "integer",
      "maximum": 10,
      "minimum": 2,
      "description": "Seller-selected minimum item count. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    },
    "percentageOff": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Seller-selected discount percentage. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_price_limit_enrollment_continue

Advance one bounded discovery step of an existing eBay enrollment and return its header. Read spellbook_ebay_price_limit_enrollment_get first for the current state version. The server chooses each discovery page; repeat from fresh readback while building, then ask the owner to review in the web app.

Argument	Type	Description
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
enrollmentId*	string	Enrollment ID returned by preparation. Required.
expectedStateVersion*	integer	Current stateVersion from enrollment readback. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "enrollmentId",
    "expectedStateVersion"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "enrollmentId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Enrollment ID returned by preparation. Required."
    },
    "expectedStateVersion": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Current stateVersion from enrollment readback. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_price_limit_enrollment_get

Read one eBay price-limit enrollment's state, coverage counts, fingerprint and original expiry. Call after preparation or continuation. Read stored baselines with spellbook_ebay_price_limit_enrollment_pages; continue building with spellbook_ebay_price_limit_enrollment_continue.

read-only

Argument	Type	Description
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
enrollmentId*	string	Enrollment ID returned by preparation. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "enrollmentId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "enrollmentId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Enrollment ID returned by preparation. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_price_limit_enrollment_pages

Read bounded stored pages of eBay enrollment identities, observed baselines, absolute bounds and exclusions. Call after spellbook_ebay_price_limit_enrollment_get. Follow nextCursor until null to inspect all stored pages; read the header again for overall completion.

read-only

Argument	Type	Description
cursor	string	Opaque nextCursor from the preceding stored-page response. Omit for the first page.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
enrollmentId*	string	Enrollment ID returned by preparation. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "enrollmentId"
  ],
  "properties": {
    "cursor": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "Opaque nextCursor from the preceding stored-page response. Omit for the first page."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "enrollmentId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Enrollment ID returned by preparation. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_price_limit_enrollment_prepare

Prepare an account-wide enrollment proposal from explicit owner-selected bounds and times. Returns a durable header and coverage counts. Explain the quiet interval prerequisite before calling: controlled price admissions and relevant membership changes can invalidate discovery. Continue with spellbook_ebay_price_limit_enrollment_continue; the owner reviews and activates in the web app.

Argument	Type	Description
scope*	string	Known ordinary live USD listings for the verified eBay account. Required.
endsAt*	string	Owner-selected exclusive admission-window end as a UTC timestamp. Required.
startsAt*	string	Owner-selected inclusive admission-window start as a UTC timestamp. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
decreaseCents*	integer	Owner-selected absolute USD cents below each observed baseline. Required; no default.
increaseCents*	integer	Owner-selected absolute USD cents above each observed baseline. Required; no default.
expectedPolicyRevision

spellbook_ebay_price_limits_get

Read active and pending eBay fixed-baseline price limits, enforcement status and missing evidence. Call before preparing a new enrollment with spellbook_ebay_price_limit_enrollment_prepare. Expiry stops new admissions; earlier admitted writes may still finish.

read-only

Argument	Type	Description
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_pricing_approval_execute

Execute the frozen targets of an owner-approved exact eBay pricing batch. First prepare with spellbook_ebay_pricing_approval_prepare and read owner approval with spellbook_ebay_pricing_approval_get. Returns durable execution and per-listing outcome evidence; read the same operation again to inspect progress.

destructive

Argument	Type	Description
operationId*	string	Exact operation ID of the owner-approved prepared batch. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "operationId"
  ],
  "properties": {
    "operationId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact operation ID of the owner-approved prepared batch. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_pricing_approval_get

Read one exact eBay pricing batch's immutable targets, owner approval state and per-listing submission and readback evidence. Call after preparation or execution. Use spellbook_ebay_pricing_approval_execute only after owner approval; keep unknown submissions distinct from observed prices.

read-only

Argument	Type	Description
operationId*	string	Exact operation ID returned by preparation. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "operationId"
  ],
  "properties": {
    "operationId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact operation ID returned by preparation. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_pricing_approval_prepare

Prepare an immutable eBay pricing batch from selected inventory items. Returns exact listing identities, executable USD cents, complete physical membership and approval state. Ask the owner to review the batch in the web app, then call spellbook_ebay_pricing_approval_get before execution.

Argument	Type	Description
itemIds*	array	Physical inventory item IDs to resolve into complete active eBay listings. The server refuses selections beyond its bounded listing or membership limit.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "itemIds"
  ],
  "properties": {
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 1000,
      "minItems": 1,
      "description": "Physical inventory item IDs to resolve into complete active eBay listings. The server refuses selections beyond its bounded listing or membership limit."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_pricing_restoration_prepare

Prepare a new exact eBay pricing approval from selected accepted source receipts. Returns eligible listing identities, typed conflicts and missing evidence. First read the source with spellbook_ebay_pricing_approval_get. The owner must choose manual automation and approve the new compensation in the web app; read its approval before spellbook_ebay_pricing_approval_execute.

Argument	Type	Description
listingIds*	array	Owner-selected canonical eBay listing IDs from the source operation. Required; duplicates are refused.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
sourceOperationId*	string	Source exact pricing operation ID containing retained accepted receipts. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "sourceOperationId",
    "listingIds"
  ],
  "properties": {
    "listingIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 25,
      "minItems": 1,
      "description": "Owner-selected canonical eBay listing IDs from the source operation. Required; duplicates are refused."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "sourceOperationId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Source exact pricing operation ID containing retained accepted receipts. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_publish

Publish owned copies from one workspace as live eBay listings, priced by a stated rule. Pass itemIds to publish one exact card. ALWAYS call it once with dryRun true and show the person the counts and the preflight before calling it again with dryRun false, because a live run creates real listings a real buyer can buy. Pricing anchors on market price, never on what the seller paid: multiplier 0.96 lists at 96% of market, and floorUsd only ever raises a price. A live run returns a queued jobId, or the reason nothing published. A queued job has listed nothing yet, so call spellbook_ebay_job_status with that jobId before telling the person any card is live.

destructive

Argument	Type	Description
binId	string	Restrict publishing to one exact bin. Omit to consider every owned copy.
dryRun	boolean	True previews the run with no live listings created. False publishes for real. Defaults to true; a live run needs an explicit false.
itemIds	array	Restrict publishing to these exact Item ids, from a prior spellbook_inventory_items_query. Pass one id to list one card. The owned-only rule still applies to each id. Omit to consider every owned copy.
floorUsd	number	A price floor in USD that only ever raises a computed price. Omit for no floor.
setCodes	array	Restrict publishing to these set codes. Omit to consider every set.
batchSize

spellbook_ebay_reprice

Preview or reprice existing live eBay listings in one seller workspace using owner-accepted saved rules or a market multiplier and optional floor. Read spellbook_agent_pricing_protection first. A workspace in saved_rules_only mode requires pricing saved_rules; the server uses its accepted rules. This is a one-run marketplace override: it changes current eBay asks, creates no listing, and saves no pricing profile or durable override. Preview first with the default dryRun true. A preview with itemIds returns its counts at once. Any other preview returns state planning and a jobId, so read its counts with spellbook_ebay_job_status. An explicit dryRun false queues an async reprice job. Read that job with spellbook_ebay_job_status until each affected listing reaches its terminal state.

destructive

Argument	Type	Description
binId	string	Restrict the run to one exact inventory bin. Omit for every live eBay listing in the workspace.
dryRun	boolean	True previews the listings and counts with no marketplace change. False queues the reprice job. Defaults to true; applying requires explicit false.
itemIds	array	Restrict the run to these exact listed Item ids from spellbook_inventory_items_query. Omit for every live eBay listing in the workspace.
pricing	string	Use saved_rules to run the owner's accepted eBay strategy without caller pricing overrides. multiplier applies a one-run override where delegated permissions allow it.
floorUsd	number

spellbook_ebay_shipping_mode_get

Read the shipping-mode preference saved for the caller's connected eBay account and whether a delegated agent last set it. workspaceId proves owner access only; the preference is account-scoped.

read-only

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_shipping_mode_set

Save the seller-selected shipping mode for the caller's connected eBay account, then return the saved preference. Read spellbook_ebay_shipping_mode_get first; call spellbook_ebay_shipping_policy_set separately to configure charges. This can affect future listing and repricing work across the account's workspaces.

destructive

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.
shippingMode*	string	Seller-selected account preference: buyer_pays_flat or free_baked_in. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "shippingMode"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    },
    "shippingMode": {
      "enum": [
        "buyer_pays_flat",
        "free_baked_in"
      ],
      "type": "string",
      "description": "Seller-selected account preference: buyer_pays_flat or free_baked_in. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_shipping_policy_get

Read the caller's connected eBay shipping charges and provider readback. workspaceId proves the caller owns a SpellBook workspace; eBay settings remain scoped to that caller's connected eBay account. Read this before changing shipping charges.

read-only

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_shipping_policy_set

Set a package flat shipping charge and optionally an envelope charge on the caller's connected eBay account, then return provider readback. Read spellbook_ebay_shipping_policy_get first; omitting the envelope amount preserves its current charge. workspaceId is checked for owner access; the connected account belongs to the caller.

destructive

Argument	Type	Description
workspaceId*	string	Workspace the caller owns; used for delegated authorization. Required.
packageFlatRateUsd*	number	Seller-selected flat package shipping charge in USD. Required.
envelopeFlatRateUsd	number	Optional seller-selected flat envelope shipping charge in USD. Omit to preserve its current amount.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "packageFlatRateUsd"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Workspace the caller owns; used for delegated authorization. Required."
    },
    "packageFlatRateUsd": {
      "type": "number",
      "maximum": 99,
      "minimum": 0,
      "description": "Seller-selected flat package shipping charge in USD. Required."
    },
    "envelopeFlatRateUsd": {
      "type": "number",
      "maximum": 99,
      "minimum": 0,
      "description": "Optional seller-selected flat envelope shipping charge in USD. Omit to preserve its current amount."
    }
  },
  "additionalProperties": false
}

spellbook_ebay_unpublish

End the live eBay listings for up to 25 exact copies, and keep each copy in inventory so it can be published again. Take Item ids from spellbook_inventory_items_query. Show the person which cards will come down and get a yes before calling, because a live listing ends at once. Returns one result per copy: unpublished, kept, no_listing, or failed.

destructive

Argument	Type	Description
itemIds*	array	Up to 25 exact Item ids whose eBay listings to end, from a prior spellbook_inventory_items_query. Required, at least one.
workspaceId*	string	The workspace that owns the copies. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "itemIds"
  ],
  "properties": {
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 25,
      "minItems": 1,
      "description": "Up to 25 exact Item ids whose eBay listings to end, from a prior spellbook_inventory_items_query. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the copies. Required."
    }
  },
  "additionalProperties": false
}

spellbook_entitlements

Read this authenticated customer's current Investor and Seller access. Flags are not proof of payment or enrollment.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_free_seller_workspace_claim

Select one workspace for free Seller access. Ask the seller to name the workspace from spellbook_workspaces_list and confirm that choice before this call. Never pick a workspace from list order or an active-workspace default. The signed-in person must own it. Re-read spellbook_workspace_plan_status after this call for the access state and observed usage.

destructive

Argument	Type	Description
workspaceId*	string	The exact workspaceId the seller explicitly selected for their one free Seller workspace. Required.
choiceConfirmed*	boolean	True only after the seller explicitly confirms this workspace choice in the current conversation. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "choiceConfirmed"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact workspaceId the seller explicitly selected for their one free Seller workspace. Required."
    },
    "choiceConfirmed": {
      "type": "boolean",
      "const": true,
      "description": "True only after the seller explicitly confirms this workspace choice in the current conversation. Required."
    }
  },
  "additionalProperties": false
}

spellbook_guides

Find a cataloged SpellBook Finance customer-agent guide for seller setup and onboarding, selling, pricing, sealed EV, or choosing a card or sealed-product strategy for a budget and workload. Use it when a customer asks how to make money with Magic, what to do with a bankroll or store credit, whether to open or resell sealed product, or which research route fits their goal. Returns catalog entries, not guide bodies. After a purpose and decision match the customer's question, read that entry's resourceUri through MCP before applying its rules or drafting the answer. The resource supplies the full guide, including domain conditions and missing-data stop rules. Use its URL only as a fallback. Public search-acquisition articles are excluded. For screening, valuing, or messaging about a Pokémon collection or Marketplace lot, read spellbook_skill with name collection-buying.

read-only

Argument	Type	Description
topic	string	Narrow results to one education topic id. Omit to search every published topic.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "topic": {
      "enum": [
        "sealed-ev",
        "pricing",
        "card-identity",
        "buylist-and-exits",
        "reprint-risk",
        "selling",
        "inventory",
        "portfolio"
      ],
      "type": "string",
      "description": "Narrow results to one education topic id. Omit to search every published topic."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_bin_ensure

Record physically confirmed cards into one inventory bin, by stating the DESIRED TOTAL quantity of each exact printing that belongs in that bin. Existing live copies count toward that total, so only a missing difference is created. Calling it twice with the same numbers creates nothing the second time. Use it for the first cards a seller enters by hand, with no CSV and no scanner. Returns the created item ids plus every candidate it refused and why.

Argument	Type	Description
binId*	string	The bin these cards physically sit in. A bin id is a container letter plus an incrementing number, like B0001, where the letter names the physical box and the number names the bag inside it. Required.
items*	array	Up to 200 exact printing rows to record in this bin. Required, at least one.
workspaceId*	string	The workspace to record these cards into. Required; writes only to this workspace.
physicallyConfirmed*	boolean	Must be true, asserting a person has physically counted these cards. The call is refused when this is omitted or false.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "binId",
    "physicallyConfirmed",
    "items"
  ],
  "properties": {
    "binId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The bin these cards physically sit in. A bin id is a container letter plus an incrementing number, like B0001, where the letter names the physical box and the number names the bag inside it. Required."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "scryfallId",
          "cardName",
          "setCode",
          "collectorNumber",
          "condition",
          "finish",
          "qty"
        ],
        "properties": {
          "qty": {
            "type": "integer",
            "maximum": 500,
            "minimum": 1,
            "description": "The DESIRED TOTAL count of this exact printing, condition and finish in this bin, never an amount to add. Required."
          },
          "finish": {
            "enum": [
              "nf",
              "fo",
              "etched",
              "surge",
              "rh",
              "1e",
              "1e-fo"
            ],
            "type": "string",
            "description": "The finish of these copies, using the values listed in this field. Pokemon supports nf (Normal/Unlimited), fo (Holofoil), rh (Reverse Holofoil), 1e (1st Edition) and 1e-fo (1st Edition Holofoil); other games have their own valid finishes. Required."
          },
          "setCode": {
            "type": "string",
            "maxLength": 20,
            "minLength": 1,
            "description": "The set code of this exact printing. Required."
          },
          "cardName": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "The card's name, echoed back in the response. Required."
          },
          "condition": {
            "enum": [
              "NM",
              "LP",
              "MP",
              "HP",
              "DMG"
            ],
            "type": "string",
            "description": "The physical condition of these copies. Required."
          },
          "scryfallId": {
            "type": "string",
            "maxLength": 64,
            "minLength": 1,
            "description": "The exact printing id, from spellbook_printings_search. Required; a wrong id records the wrong card."
          },
          "collectorNumber": {
            "type": "string",
            "maxLength": 20,
            "minLength": 1,
            "description": "The collector number of this exact printing. Required."
          },
          "acquisitionPrice": {
            "type": "number",
            "maximum": 1000000,
            "minimum": 0,
            "description": "Per-copy acquisition cost in USD. When it is omitted or zero, the server records an implied per-card cost from the set's box price instead. Pass the real cost when the person knows it."
          },
          "acquisitionSource": {
            "type": "string",
            "default": "agent_intake",
            "maxLength": 100,
            "minLength": 1,
            "description": "Provenance tag for these rows. Defaults to agent_intake; omit unless a different source genuinely applies."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 200,
      "minItems": 1,
      "description": "Up to 200 exact printing rows to record in this bin. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to record these cards into. Required; writes only to this workspace."
    },
    "physicallyConfirmed": {
      "type": "boolean",
      "const": true,
      "description": "Must be true, asserting a person has physically counted these cards. The call is refused when this is omitted or false."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_holdings

Read one page of what a seller's own workspace holds, aggregated to one row per printing, finish and condition. Each row carries card name, set code, collector number, variant label, quantity owned, quantity available, the current unit market price and the resolved minimum-sell floor with the tier that produced it. Call this to answer what is in the collection, what it is worth, what is already listed versus still available, and which rows sit near their floor. It reports holdings; it does not rank them, pick what to sell, or state a listing's live marketplace status.

read-only

Argument	Type	Description
limit	integer	Maximum rows to return, 1 to 500. Omit for the default of 100.
cursor	string	Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page.
workspaceId*	string	The workspace to read holdings for. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "description": "Maximum rows to return, 1 to 500. Omit for the default of 100."
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "description": "Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to read holdings for. Required."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_import_csv

Import a seller's own ManaBox export or TCGplayer inventory export into one workspace, the same import the SpellBook Finance web app runs. The server parses the CSV, resolves each row to an exact printing, preserves mapped location labels or assigns fallback bins, and creates one inventory copy per card. TCGplayer Pokémon and Riftbound rows require the catalog's exact game, provider product identity, finish, condition, and language; incomplete or mismatched rows are skipped with a repair reason and never default to Magic, English, or nonfoil. Sending the identical CSV again returns the first result with duplicate true and creates nothing. Returns the importId, how many copies were written, the bins used, and every row it could not parse or skipped.

Argument	Type	Description
csv*	string	The full CSV text, header row included, exactly as the export produced it. Required. At most 200,000 characters.
source*	string	Which export this is: manabox for a ManaBox CSV (needs Scryfall ID, Quantity, Condition and Foil columns), tcg for a TCGplayer seller inventory export (needs the TCGplayer Id column). Required.
binName	string	A human name for that one bin, 1 to 48 letters, digits, spaces, dashes or underscores. Honored only when oneBinPerUpload is true. A name another import already holds is refused.
binPrefix	string	One capital letter that starts fallback bin codes for copies without a mapped location, e.g. C gives C0001, C0002. Defaults to C.
totalCost	number

spellbook_inventory_incoming

Read what a workspace has bought or saved that has not arrived yet, one group per marketplace order or precon deck import. Each group carries its acquisitionSource, a readable title, the copy and card counts, the total cost, the date it was recorded and the bins its copies are assigned to. Call this to answer what is still on the way, or to find the acquisitionSource to receive. It reports pending groups; it does not track a package or say when one will arrive.

read-only

Argument	Type	Description
workspaceId*	string	The workspace whose incoming inventory to read, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose incoming inventory to read, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_incoming_receive

Mark every pending copy in the named orders or precon imports as received, which makes them owned inventory that can be listed and sold. Returns how many copies were received, their total cost and the bins they belong in. Call it when the customer says the package arrived and they counted the cards. Read spellbook_inventory_incoming first to get each acquisitionSource.

Argument	Type	Description
workspaceId*	string	The workspace that holds the pending copies. Required; writes only to this workspace.
acquisitionSources*	array	The acquisitionSource of each order or import to receive, exactly as spellbook_inventory_incoming or spellbook_purchase_incoming_record returned it. Required, at least one.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "acquisitionSources"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that holds the pending copies. Required; writes only to this workspace."
    },
    "acquisitionSources": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "The acquisitionSource of each order or import to receive, exactly as spellbook_inventory_incoming or spellbook_purchase_incoming_record returned it. Required, at least one."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_items_query

Read one private page of existing physical Items matching an exact acquisition source, exact bins, or printing, finish and condition groups. Coordinate filters narrow source or group results. Each Item carries scanPlacement, its approximate position in its scanned bin as ordinal of total, or null when it was never scanned there.

read-only

Argument	Type	Description
bins	array	Restrict results to these exact bin names, up to 25. Omit to search every bin.
limit	integer	Maximum Items to return, 1 to 1000. Omit for the default of 20.
cursor	string	Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page.
groups	array	Restrict results to these exact printing, finish and condition groups, up to 25. Omit to skip this filter.
workspaceId*	string	The workspace to read Items from. Required.
acquisitionSource	string	Restrict results to one exact acquisition source, such as a bulk-import ID. Combine with bins or groups to narrow it further.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "bins": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64,
        "minLength": 1
      },
      "maxItems": 25,
      "description": "Restrict results to these exact bin names, up to 25. Omit to search every bin."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum Items to return, 1 to 1000. Omit for the default of 20."
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "description": "Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "groups": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "scryfallId",
          "finish",
          "condition"
        ],
        "properties": {
          "finish": {
            "type": "string",
            "minLength": 1,
            "description": "The finish to match, e.g. nf, fo, etched or surge. Required."
          },
          "condition": {
            "type": "string",
            "minLength": 1,
            "description": "The condition to match, e.g. NM, LP, MP, HP or DMG. Required."
          },
          "scryfallId": {
            "type": "string",
            "minLength": 1,
            "description": "The printing's scryfallId. Required."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 25,
      "description": "Restrict results to these exact printing, finish and condition groups, up to 25. Omit to skip this filter."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to read Items from. Required."
    },
    "acquisitionSource": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Restrict results to one exact acquisition source, such as a bulk-import ID. Combine with bins or groups to narrow it further."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_location_confirm

Save up to 25 existing Item bin locations after comparing each expectedBins observation with current state. A fresh Item query is required before and after the save.

destructive

Argument	Type	Description
toBin*	string	The bin these Items are being confirmed into. Required.
itemIds*	array	Up to 25 exact Item ids to move, from a prior spellbook_inventory_items_query. Required, at least one.
workspaceId*	string	The workspace the Items belong to. Required.
expectedBins*	array	One prior-bin observation per itemId in itemIds, up to 25. Required; a missing or changed Item rejects the whole batch.
sourceSignalId	string	An id linking this confirmation to its originating signal. Omit when there is none.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "itemIds",
    "toBin",
    "expectedBins"
  ],
  "properties": {
    "toBin": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "The bin these Items are being confirmed into. Required."
    },
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 25,
      "minItems": 1,
      "description": "Up to 25 exact Item ids to move, from a prior spellbook_inventory_items_query. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the Items belong to. Required."
    },
    "expectedBins": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "itemId",
          "binId"
        ],
        "properties": {
          "binId": {
            "type": "string",
            "minLength": 1,
            "description": "The bin this Item was last observed in, before the move. Required."
          },
          "itemId": {
            "type": "string",
            "minLength": 1,
            "description": "The Item id this observation is about. Required."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 25,
      "minItems": 1,
      "description": "One prior-bin observation per itemId in itemIds, up to 25. Required; a missing or changed Item rejects the whole batch."
    },
    "sourceSignalId": {
      "type": "string",
      "minLength": 1,
      "description": "An id linking this confirmation to its originating signal. Omit when there is none."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_management_get

Read the connected TCGplayer or ManaPool account's saved listing scope, server-reported legacy full-account restore eligibility, managed-copy count, and selected-policy membership-key count. The selected key count does not total legacy all-mode remote listings. Supply candidateIds only from SpellBook Finance's existing named listing rows or holdings. Results report saved facts and unresolved identities; they do not choose which rows to manage. New accounts start with no managed listings. A backfilled legacy account may restore full-account management after switching to named listings.

read-only

Argument	Type	Description
channel*	string	The connected seller channel. Required.
workspaceId*	string	The seller workspace to read. Required.
candidateIds	array	At most 100 candidate IDs from existing SpellBook listing rows. Omit to read account scope and counts only.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "channel"
  ],
  "properties": {
    "channel": {
      "enum": [
        "tcg",
        "manapool"
      ],
      "type": "string",
      "description": "The connected seller channel. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller workspace to read. Required."
    },
    "candidateIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 64,
        "minLength": 1
      },
      "maxItems": 100,
      "description": "At most 100 candidate IDs from existing SpellBook listing rows. Omit to read account scope and counts only."
    }
  },
  "additionalProperties": false
}

spellbook_inventory_management_set

Change one seller-owned channel's saved listing scope. Read spellbook_inventory_management_get first. Switching legacy all mode to selected mode clears management for all current listings. On an eligible backfilled account, restore_legacy_all explicitly manages every current and future listing on that connected seller account; saved automation settings remain unchanged. In selected mode, use a named candidateId from current SpellBook Finance rows to manage or stop managing a complete listing. Stopping management leaves its live listing and order history intact. These actions save permission for existing automation and do not enable automation or publish a listing.

destructive

No arguments.

Input schema (JSON)

{
  "oneOf": [
    {
      "type": "object",
      "required": [
        "workspaceId",
        "channel",
        "action",
        "expectedRevision"
      ],
      "properties": {
        "action": {
          "type": "string",
          "const": "switch_to_selected"
        },
        "channel": {
          "enum": [
            "tcg",
            "manapool"
          ],
          "type": "string",
          "description": "The connected seller channel. Required."
        },
        "workspaceId": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "The seller workspace. Required."
        },
        "expectedRevision": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0,
          "description": "The revision returned by the latest scope read. Required."
        }
      },
      "additionalProperties": false
    },
    {
      "type": "object",
      "required": [
        "workspaceId",
        "channel",
        "action",
        "expectedRevision"
      ],
      "properties": {
        "action": {
          "type": "string",
          "const": "restore_legacy_all",
          "description": "Restore every current and future listing only when spellbook_inventory_management_get reports legacyAllEligible true. Required."
        },
        "channel": {
          "enum": [
            "tcg",
            "manapool"
          ],
          "type": "string",
          "description": "The connected seller channel. Required."
        },
        "workspaceId": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "The seller workspace. Required."
        },
        "expectedRevision": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0,
          "description": "The revision returned by the latest scope read. Required."
        }
      },
      "additionalProperties": false
    },
    {
      "type": "object",
      "required": [
        "workspaceId",
        "channel",
        "action",
        "candidateId",
        "managed",
        "expectedRevision"
      ],
      "properties": {
        "action": {
          "type": "string",
          "const": "set_candidate"
        },
        "channel": {
          "enum": [
            "tcg",
            "manapool"
          ],
          "type": "string",
          "description": "The connected seller channel. Required."
        },
        "managed": {
          "type": "boolean",
          "description": "True to manage all copies of this listing; false to stop managing it. Required."
        },
        "candidateId": {
          "type": "string",
          "maxLength": 64,
          "minLength": 1,
          "description": "One exact candidateId returned by spellbook_inventory_management_get for a current existing row. Required."
        },
        "workspaceId": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "description": "The seller workspace. Required."
        },
        "expectedRevision": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0,
          "description": "The revision returned by the latest scope read. Required."
        }
      },
      "additionalProperties": false
    }
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

spellbook_inventory_precon_import

Add one or more opened Commander precon decks to inventory as individual cards, the same Add Commander deck flow the SpellBook web app runs. The server reads the cached decklist for that TCGplayer product, creates one inventory copy per card at the exact deck printing, assigns bins, and splits the price paid across the cards. Returns the importId, how many copies were written, and the count placed in each bin.

Argument	Type	Description
binPrefix*	string	One capital letter that starts the auto-assigned bin codes, e.g. C gives C0001. Required.
copyCount	integer	How many identical decks were opened, 1 to 20. Defaults to 1.
workspaceId*	string	The workspace to add the cards to, from spellbook_workspaces_list. Required; writes only to this workspace.
paidPriceUsd*	number	What the seller paid for ONE deck in USD. Required. Send 0 only when the deck cost nothing. Every copy of the deck is recorded at this price.
tcgProductId*	integer	Exact TCGplayer product id of the sealed precon deck, from spellbook_sealed_product_search. Required. A product that is not a single Commander or Riftbound precon deck is refused.
oneBinPerDeck	boolean	True puts each deck in its own fresh bin. Defaults to false, which packs the cards into the rolling bin sequence.

spellbook_item_photo_upload_link

Get a link where the seller uploads their own phone photo of one inventory copy, so the next eBay listing shows that photo in place of catalog art. Use it when the seller wants buyers to see the real card, or when catalog art is wrong or missing. Take itemId from spellbook_inventory_items_query or spellbook_inventory_holdings. Give the seller the returned url and tell them to open it on their phone, then take or pick a photo of the card front. No photo passes through you. After they say it is saved, call spellbook_ebay_publish for that copy.

read-only

Argument	Type	Description
itemId*	string	One inventory copy's itemId, from spellbook_inventory_items_query or spellbook_inventory_holdings. Required.
workspaceId*	string	The workspace that holds the copy. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "itemId"
  ],
  "properties": {
    "itemId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "One inventory copy's itemId, from spellbook_inventory_items_query or spellbook_inventory_holdings. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that holds the copy. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_japan_source_scan

Read the latest bounded Japan sourcing cohort: English Riftbound cards sold in Japan (riftbound-jp), Japanese-language Magic promos (japanese-promos), or exact-language Pokemon cards (pokemon, pokemon-en, pokemon-ja). Returns every tracked target's actual observation time, verified offers, exact reference prices with price kinds, unresolved listing URLs and recorded blockers, source status and freshness policy. publishedAt is snapshot publication time and does not refresh an older target. Sold and unrelated observations are not purchase candidates. Missing costs remain unknown; no buying recommendation or profit is provided.

read-only

Argument	Type	Description
cohortId	string	English Riftbound cards sold in Japan, Japanese-language Magic promos, or one exact-language Pokemon cohort. Use pokemon-en or pokemon-ja to keep source observations isolated. Defaults to riftbound-jp.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "cohortId": {
      "enum": [
        "riftbound-jp",
        "japanese-promos",
        "pokemon",
        "pokemon-en",
        "pokemon-ja"
      ],
      "type": "string",
      "default": "riftbound-jp",
      "description": "English Riftbound cards sold in Japan, Japanese-language Magic promos, or one exact-language Pokemon cohort. Use pokemon-en or pokemon-ja to keep source observations isolated. Defaults to riftbound-jp."
    }
  },
  "additionalProperties": false
}

spellbook_japanese_sourcing

Read Japanese-market supply offers for the Japanese promo cohort from Mercari, Hareruya and Bigweb, each beside the comparison prices SpellBook holds on TCGplayer, ManaPool and eBay. Every row carries one exact supply offer with its printing identity, the merchant's own condition grade and its normalized equivalent, the native unit price with its currency, quantity, availability, and its own observedAt and staleAfter stamps; then every comparison reference with its kind and typed comparisonBasis, a deterministic selectedReference with the selectionRule that chose it, and a providerStatus row for each comparison source explaining why it is ok, missing, stale, failed or incompatible. grossDifferenceUsd is an asking spread and is null unless printing, language, finish, unit basis and condition equivalence all hold; netDifferenceUsd stays null because this read carries no costs. Rows come back in source order, and nothing is ranked, scored or recommended for you.

read-only

Argument	Type	Description
limit	integer	Maximum offers in this page. Page with cursor to traverse the rest; a short page is not proof the cohort ended.
cursor	string	The opaque nextCursor from the previous page, passed back unchanged. It is signed by the server; never construct, decode or edit one.
buySources	array	Which Japanese supply sources to read. Omit for all three. Narrow it only when the person named a merchant; a source you drop is simply absent, never proven empty.
includeStale	boolean	True also returns offers whose staleAfter has already passed, with their stamps intact. Default false returns only offers still inside their freshness window.

spellbook_manapool_automation_set

Set one workspace's ManaPool automation mode, which decides whether SpellBook creates, updates, delists, and reprices ManaPool listings by itself. This changes public ManaPool behavior for the workspace, only the workspace owner may call it, and the agent sets a mode only after the seller chose one. The modes: manual: SpellBook creates no ManaPool listings and sends no quantity changes or delistings, but it keeps repricing your existing ManaPool listings. assisted: SpellBook plans the ManaPool listing changes it would make but sends none of them and offers no approval step, and it keeps repricing your existing ManaPool listings. automatic: SpellBook creates, updates, and delists ManaPool listings as your inventory changes and reprices existing ones, once the workspace passed a ManaPool test publish and while ManaPool reports the account ready to sell. paused: SpellBook sends nothing to ManaPool: no new listings, no quantity changes, no delistings, and no repricing.

destructive

Argument	Type	Description
mode*	string	The mode the seller chose: manual, assisted, automatic, or paused. Required.
workspaceId*	string	The workspace whose ManaPool automation mode to set. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "mode"
  ],
  "properties": {
    "mode": {
      "enum": [
        "manual",
        "assisted",
        "automatic",
        "paused"
      ],
      "type": "string",
      "description": "The mode the seller chose: manual, assisted, automatic, or paused. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose ManaPool automation mode to set. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_manapool_connect_link

Get the SpellBook Finance page where the seller connects ManaPool, and guide them through it. Call spellbook_manapool_connection_status first. Save the seller's return address with spellbook_return_address_save before you hand over the link, because the page fills ManaPool's tax address from it. Hand the seller only this one link. The page itself links to ManaPool's token page, where a seller with no ManaPool account signs up first and then creates an access token starting mpat_. Tell them the SpellBook page already shows their email and return address, so they paste only the token. Call spellbook_manapool_connection_status after they finish. The agent never receives or submits the credential.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_manapool_connection_status

Check whether this signed-in customer's ManaPool seller account is connected to SpellBook Finance. Call this before requesting a setup link and again after the seller finishes the setup form. It returns a masked account identifier and stored connection timestamps. If connected is false, call spellbook_manapool_connect_link.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_manapool_sync_apply

Send a previewed batch of changes to ManaPool, creating, repricing and removing real listings. Takes the previewToken from spellbook_manapool_sync_preview, which must still be valid. Applies at most maxActions in one call and returns remainingActionCount with nextActionCursor, so a full book takes several calls. Show the person the preview before the first call, not after.

destructive

Argument	Type	Description
floorUsd	number	Must match the floorUsd used to build the preview, or the token is refused.
maxActions	integer	Maximum actions to apply in this call, 1 to 250. Omit for the default of 50; call again with the same token to continue.
multiplier	number	Must match the multiplier used to build the preview, or the token is refused.
workspaceId*	string	The workspace whose previewed changes to apply. Required.
previewToken*	string	The previewToken from spellbook_manapool_sync_preview. Must still be valid; a stale token is refused.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "previewToken"
  ],
  "properties": {
    "floorUsd": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0,
      "description": "Must match the floorUsd used to build the preview, or the token is refused."
    },
    "maxActions": {
      "type": "integer",
      "default": 50,
      "maximum": 250,
      "minimum": 1,
      "description": "Maximum actions to apply in this call, 1 to 250. Omit for the default of 50; call again with the same token to continue."
    },
    "multiplier": {
      "type": "number",
      "maximum": 10,
      "description": "Must match the multiplier used to build the preview, or the token is refused.",
      "exclusiveMinimum": 0
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose previewed changes to apply. Required."
    },
    "previewToken": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "The previewToken from spellbook_manapool_sync_preview. Must still be valid; a stale token is refused."
    }
  },
  "additionalProperties": false
}

spellbook_manapool_sync_preview

Compare one workspace's inventory against what is live on ManaPool, and return the exact changes a sync would make. Every action is listed with its kind: upsert to create or change a listing, delist to remove one, blocked where a cross-channel check refused it. Nothing is sent to ManaPool by this call. Show the person the summary and the counts, then call spellbook_manapool_sync_apply with the previewToken this returns.

read-only

Argument	Type	Description
floorUsd	number	A price floor in USD for this preview. Omit to use the workspace's stored floor.
multiplier	number	Price multiplier applied to market price for this preview. Omit to use the workspace's stored pricing.
workspaceId*	string	The workspace to compare against live ManaPool state. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "floorUsd": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0,
      "description": "A price floor in USD for this preview. Omit to use the workspace's stored floor."
    },
    "multiplier": {
      "type": "number",
      "maximum": 10,
      "description": "Price multiplier applied to market price for this preview. Omit to use the workspace's stored pricing.",
      "exclusiveMinimum": 0
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to compare against live ManaPool state. Required."
    }
  },
  "additionalProperties": false
}

spellbook_marketplace_listings_adopt_apply

Adopt the listings in a ready preview from spellbook_marketplace_listings_adopt_preview. Each remote copy is linked to an owned item or gets a new item in the channel's import bin (EBAY-IMPORT, TCG-IMPORT or MANAPOOL-IMPORT), and the listing is recorded as managed by SpellBook. Each adopted printing gets an exact price lock at its live price. Nothing on the marketplace is edited, ended or relisted, and nothing is published. Applying runs in the background. The first answer has applyStatus applying. Call spellbook_marketplace_listings_adopt_preview with previewId latest until applyStatus is applied. Show the person the preview before the first call.

destructive

Argument	Type	Description
channel	string	The marketplace of the preview: ebay, tcg for TCGplayer, or manapool. Defaults to ebay.
maxUnits	integer	Adopt whole listings, highest live price first, until this many copies. Omit to adopt every adoptable listing. Pass it only when the person asks to adopt fewer copies. The allowance never requires it.
previewId*	string	The previewId of a ready, unexpired preview from spellbook_marketplace_listings_adopt_preview. Required.
workspaceId*	string	The workspace that owns the preview. Required. Only the workspace owner can apply.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "previewId"
  ],
  "properties": {
    "channel": {
      "enum": [
        "ebay",
        "tcg",
        "manapool"
      ],
      "type": "string",
      "default": "ebay",
      "description": "The marketplace of the preview: ebay, tcg for TCGplayer, or manapool. Defaults to ebay."
    },
    "maxUnits": {
      "type": "integer",
      "maximum": 1000000,
      "description": "Adopt whole listings, highest live price first, until this many copies. Omit to adopt every adoptable listing. Pass it only when the person asks to adopt fewer copies. The allowance never requires it.",
      "exclusiveMinimum": 0
    },
    "previewId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$",
      "description": "The previewId of a ready, unexpired preview from spellbook_marketplace_listings_adopt_preview. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the preview. Required. Only the workspace owner can apply."
    }
  },
  "additionalProperties": false
}

spellbook_marketplace_listings_adopt_preview

Read the live listings on the workspace's connected eBay, TCGplayer or ManaPool account and preview how each one maps to an exact printing, without changing the marketplace or inventory. Omit previewId to start a read. The read runs in the background, so the first answer has status queued or reading. Call again with previewId latest until status is ready. A ready preview lists adoptable listings with the printing, finish and condition read from each one, the facts that named it (matchSource), and how many copies link to owned items or need a new item. Unmatched listings carry one reason each. Show the person the counts and cap, then call spellbook_marketplace_listings_adopt_apply with the previewId.

Argument	Type	Description
channel	string	The marketplace whose live listings to adopt: ebay, tcg for TCGplayer, or manapool. Defaults to ebay.
previewId	string	Omit to start a new read of the live listings. Pass latest, or a previewId from an earlier call, to read a stored preview without a new eBay read.
workspaceId*	string	The workspace whose connected marketplace account to read. Required. Only the workspace owner can start a read.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "channel": {
      "enum": [
        "ebay",
        "tcg",
        "manapool"
      ],
      "type": "string",
      "default": "ebay",
      "description": "The marketplace whose live listings to adopt: ebay, tcg for TCGplayer, or manapool. Defaults to ebay."
    },
    "previewId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$",
      "description": "Omit to start a new read of the live listings. Pass latest, or a previewId from an earlier call, to read a stored preview without a new eBay read."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose connected marketplace account to read. Required. Only the workspace owner can start a read."
    }
  },
  "additionalProperties": false
}

spellbook_marketplace_onboarding

Read how a seller onboards to one channel-lane marketplace and where this workspace's lane stands. It returns the venue's ordered onboarding steps with who does each step, what each needs, where it happens, and its sources, plus the venue's fees, seller levels, and accepted conditions. It also returns the workspace's lane: whether it exists and is enabled, whether SpellBook Finance holds the seller's key for the venue, whether the venue flag is on, whether SpellBook sync exists for the venue, and live and unconfirmed listing counts. Call it when a seller asks how to start selling on Misprint, or why nothing lists there. Walk the seller through the steps they have not done. While lane.connected is false, hand the seller the url of the step that connects the venue to SpellBook Finance, where the seller pastes the key themselves. Call this tool again after they finish. For eBay or ManaPool, call spellbook_ebay_connection_status or spellbook_manapool_connection_status.

read-only

Argument	Type	Description
marketplace*	string	The channel-lane marketplace whose onboarding steps and lane state to read.
workspaceId*	string	The workspace whose lane to read. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "marketplace"
  ],
  "properties": {
    "marketplace": {
      "enum": [
        "cardtrader",
        "ebay",
        "manapool",
        "misprint",
        "shopify"
      ],
      "type": "string",
      "description": "The channel-lane marketplace whose onboarding steps and lane state to read."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose lane to read. Required."
    }
  },
  "additionalProperties": false
}

spellbook_movers

Read published daily/weekly card price movers or supported 30d/90d sealed reports. Returns gainers/losers, reported game/printing/finish when supplied, current and previous USD prices, stored pctChange, swing30d, cardUrl and run/publication dates. Daily/weekly reported percentages and direction lists have producer caps over covered source candidates; read the limits. Capped ties do not identify the largest uncapped market move. For what increased this week, use window=weekly, then read the pricing guide through spellbook_guides and its returned resource URI for window, cap and clock interpretation. A printing price read qualifies one reported candidate; missing source dates remain unknown.

read-only

Argument	Type	Description
game	string	Restrict card movers to one game. Omit for the default Magic board.
window	string	Which price-change window to read: daily, weekly, 30d or 90d. Omit for the default window.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "game": {
      "enum": [
        "mtg",
        "riftbound",
        "pokemon"
      ],
      "type": "string",
      "description": "Restrict card movers to one game. Omit for the default Magic board."
    },
    "window": {
      "enum": [
        "daily",
        "weekly",
        "30d",
        "90d"
      ],
      "type": "string",
      "description": "Which price-change window to read: daily, weekly, 30d or 90d. Omit for the default window."
    }
  },
  "additionalProperties": false
}

spellbook_order_proof_photos

Read the packing proof photos for ONE order: a view link for each pull line the packer photographed, with card name, finish, condition and capture time, plus the order's lines that have no photo. Use it to answer whether an order's cards were photographed before shipping, or to gather evidence for a dispute. Photos come from the packer's own camera in the pull flow. This tool only reads them and cannot upload one.

read-only

Argument	Type	Description
orderId*	string	The marketplace's order id exactly as the order lists it. Required.
marketplace*	string	The marketplace the order came from. Required.
workspaceId*	string	The workspace that shipped the order, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "marketplace",
    "orderId"
  ],
  "properties": {
    "orderId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The marketplace's order id exactly as the order lists it. Required."
    },
    "marketplace": {
      "enum": [
        "tcg",
        "manapool",
        "ebay",
        "shopify",
        "cardtrader"
      ],
      "type": "string",
      "description": "The marketplace the order came from. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that shipped the order, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pokemon_arbitrage_spreads

Read bounded Pokemon acquisition and exit quote facts for exact product identity, preserving quote basis, currency, observation time, source reference, source URLs, comparisons, missingFields and limitations. This read compares observed sources; it does not rank opportunities, recommend a purchase, or execute a transaction.

read-only

Argument	Type	Description
limit	integer	Maximum rows to return, from 1 to 100. Defaults to 25.
finish	string	Optional exact finish filter.
cohortId	string	Optional Pokemon cohort. Use pokemon-ja or pokemon-en to keep language evidence isolated.
language	string	Optional exact language filter.
condition	string	Optional condition filter.
productId	string	Optional exact Pokemon catalog product id from spellbook_printings_search.
proxyFeeUsd	any	Optional proxy fee assumption in USD; omitted keeps landed cost incomplete.
importDutyRate	any

spellbook_pokemon_ath

Read the latest Pokemon all-time-high facts for the retained daily snapshot. Rows preserve exact product identity, language, finish, variant, source date, previous ATH and history coverage. This is a facts-only read; unavailable or partial history stays explicit in availability, missingFields and limitations.

read-only

Argument	Type	Description
date	string	Optional retained snapshot date, YYYY-MM-DD. Omit to read the latest snapshot.
game*	string	The game to read. Must be pokemon.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "game"
  ],
  "properties": {
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Optional retained snapshot date, YYYY-MM-DD. Omit to read the latest snapshot."
    },
    "game": {
      "type": "string",
      "const": "pokemon",
      "description": "The game to read. Must be pokemon."
    }
  },
  "additionalProperties": false
}

spellbook_pokemon_market_analytics

Read exact identity scoped Pokemon market facts for ONE catalog product: language, finish, condition, independent retail fair value, observed supply depth, versioned SCORE factors and Limitless demand coverage. The response keeps qualified values null when source count or comparable history is missing, and names missingFields and limitations. It reports facts only; it does not rank cards, recommend an action or infer a missing source.

read-only

Argument	Type	Description
cardId*	string	The exact Pokemon catalog product id from spellbook_printings_search, such as pokemon:tcgp:12345. Required.
finish*	string	Observed finish: nf regular, fo holo, rh reverse holo, 1e first edition, or 1e-fo first edition holo. Required.
language*	string	Observed card language, such as en or ja. Required; do not infer from the seller location.
condition*	string	Observed condition: NM, LP, MP, HP, or DMG. Required; do not assume near mint.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "cardId",
    "language",
    "finish",
    "condition"
  ],
  "properties": {
    "cardId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The exact Pokemon catalog product id from spellbook_printings_search, such as pokemon:tcgp:12345. Required."
    },
    "finish": {
      "enum": [
        "nf",
        "fo",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "Observed finish: nf regular, fo holo, rh reverse holo, 1e first edition, or 1e-fo first edition holo. Required."
    },
    "language": {
      "type": "string",
      "minLength": 1,
      "description": "Observed card language, such as en or ja. Required; do not infer from the seller location."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "Observed condition: NM, LP, MP, HP, or DMG. Required; do not assume near mint."
    }
  },
  "additionalProperties": false
}

spellbook_pokemon_metagame_archetype

Read observed Pokemon archetype and card facts for one format and exact archetype name from recent Limitless tournament decklists. The response preserves source coverage, card prices, truncation, missingFields and limitations. It reports observations and does not recommend a deck or purchase.

read-only

Argument	Type	Description
limit	integer	Maximum cards to return, from 1 to 100. Defaults to 100.
format*	string	Pokemon format. Required.
archetypeName*	string	Exact observed archetype name. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "format",
    "archetypeName"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum cards to return, from 1 to 100. Defaults to 100."
    },
    "format": {
      "enum": [
        "standard",
        "expanded",
        "unlimited"
      ],
      "type": "string",
      "description": "Pokemon format. Required."
    },
    "archetypeName": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact observed archetype name. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pokemon_metagame_card

Read observed Pokemon card demand facts for one exact catalog product, optionally narrowed to one format. The response preserves exact card identity, sample windows, counts, prices, coverage, missingFields and limitations. It reports observations and does not rank or recommend a card.

read-only

Argument	Type	Description
limit	integer	Maximum observations to return, from 1 to 100. Defaults to 20.
cardId*	string	Exact Pokemon catalog product id from spellbook_printings_search. Required.
format	string	Optional Pokemon format filter.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "cardId"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum observations to return, from 1 to 100. Defaults to 20."
    },
    "cardId": {
      "type": "string",
      "pattern": "^pokemon:tcgp:[1-9]\\d*$",
      "description": "Exact Pokemon catalog product id from spellbook_printings_search. Required."
    },
    "format": {
      "enum": [
        "standard",
        "expanded",
        "unlimited"
      ],
      "type": "string",
      "description": "Optional Pokemon format filter."
    }
  },
  "additionalProperties": false
}

spellbook_pokemon_metagame_overview

Read observed Pokemon archetype coverage for one format from recent Limitless tournament decklists. The response preserves archetype facts, sample coverage, truncation, missingFields and limitations. It does not measure the whole player population or predict demand.

read-only

Argument	Type	Description
limit	integer	Maximum archetypes to return, from 1 to 100. Defaults to 50.
format*	string	Pokemon format. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "format"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum archetypes to return, from 1 to 100. Defaults to 50."
    },
    "format": {
      "enum": [
        "standard",
        "expanded",
        "unlimited"
      ],
      "type": "string",
      "description": "Pokemon format. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pokemon_tcg_staged_preview

Preview the TCGplayer CSV rows for 1 to 25 exact Pokemon physical inventory copies in one workspace. Call this after the seller selects the copies they want to inspect. It returns the existing staged-preview rows and CSV; it queues nothing, publishes nothing, and offers no publish or export follow-up.

read-only

Argument	Type	Description
itemIds*	array	The exact Item ids selected by the seller, 1 to 25 unique non-empty values. Required; each copy must be owned and belong to Pokemon.
workspaceId*	string	The workspace that owns every selected Pokemon inventory copy. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "itemIds"
  ],
  "properties": {
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 25,
      "minItems": 1,
      "description": "The exact Item ids selected by the seller, 1 to 25 unique non-empty values. Required; each copy must be owned and belong to Pokemon."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns every selected Pokemon inventory copy. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_amendment_create

Create one bounded seller pricing amendment from a selector, marketplace scope, absolute multiplier and optional protected band. Returns saved readback. The server retains its adaptive default internally; this tool has no demand behavior input and does not publish or reprice.

Argument	Type	Description
mode*	object	Absolute multiplier and optional protected band. Required.
name*	string	Seller-selected amendment name. Required.
notes	any	Optional seller notes; null clears notes.
enabled	boolean	Whether the amendment starts enabled. Omit for enabled.
priority*	integer	Seller-selected precedence priority. Required.
selector*	object	The bounded inventory selector. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
marketplaceScope*	any	Marketplace scope. Required.

spellbook_pricing_amendment_delete

Delete one saved pricing amendment by exact amendment id and return a deletion readback. This changes saved configuration and does not publish or trigger repricing.

destructive

Argument	Type	Description
amendmentId*	string	The exact saved amendment id from a prior amendment read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "amendmentId"
  ],
  "properties": {
    "amendmentId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved amendment id from a prior amendment read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_amendment_get

Read one saved pricing amendment's selector, marketplace scope, absolute multiplier, optional protected band, enabled state, priority and timestamps. Use it before an update, preview or delete.

read-only

Argument	Type	Description
amendmentId*	string	The exact saved amendment id from a prior amendment read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "amendmentId"
  ],
  "properties": {
    "amendmentId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved amendment id from a prior amendment read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_amendment_preview

Start or run a bounded preview for one saved amendment or one seller-selected draft. Returns customer-safe per-channel impact counts and status evidence, with no raw inventory rows or demand telemetry. Preview is not publication.

Argument	Type	Description
channels	array	Optional marketplace channels to preview.
amendment	object	Draft amendment; provide this or amendmentId.
amendmentId	string	The exact saved amendment id from a prior amendment read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "channels": {
      "type": "array",
      "items": {
        "enum": [
          "ebay",
          "tcg",
          "manapool",
          "shopify",
          "cardtrader"
        ],
        "type": "string"
      },
      "maxItems": 5,
      "minItems": 1,
      "description": "Optional marketplace channels to preview."
    },
    "amendment": {
      "type": "object",
      "required": [
        "priority",
        "selector",
        "marketplaceScope",
        "mode"
      ],
      "properties": {
        "mode": {
          "type": "object",
          "required": [
            "multiplier"
          ],
          "properties": {
            "multiplier": {
              "type": "number",
              "description": "Absolute multiplier applied by this amendment. Required.",
              "exclusiveMinimum": 0
            },
            "protectedBand": {
              "type": "object",
              "required": [
                "thresholdUsd",
                "multiplier"
              ],
              "properties": {
                "multiplier": {
                  "type": "number",
                  "description": "Protected multiplier at or above the threshold.",
                  "exclusiveMinimum": 0
                },
                "thresholdUsd": {
                  "type": "number",
                  "description": "Original market anchor threshold in USD.",
                  "exclusiveMinimum": 0
                }
              },
              "description": "Optional seller-approved protected band.",
              "additionalProperties": false
            }
          },
          "description": "Preview absolute multiplier and protected band.",
          "additionalProperties": false
        },
        "enabled": {
          "type": "boolean",
          "default": true,
          "description": "Whether the draft is enabled for preview."
        },
        "priority": {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": -9007199254740991,
          "description": "Preview precedence priority."
        },
        "selector": {
          "type": "object",
          "properties": {
            "finish": {
              "enum": [
                "nf",
                "fo",
                "etched",
                "surge",
                "rh",
                "1e",
                "1e-fo"
              ],
              "type": "string",
              "description": "Optional finish selector."
            },
            "setCode": {
              "type": "string",
              "maxLength": 32,
              "minLength": 1,
              "description": "Set code selector."
            },
            "condition": {
              "enum": [
                "NM",
                "LP",
                "MP",
                "HP",
                "DMG"
              ],
              "type": "string",
              "description": "Optional condition selector."
            },
            "scryfallId": {
              "type": "string",
              "maxLength": 200,
              "minLength": 1,
              "description": "Exact Scryfall printing selector. Requires setCode when supplied."
            },
            "releaseFamilyCode": {
              "type": "string",
              "maxLength": 32,
              "minLength": 1,
              "description": "Release family selector."
            },
            "originalAnchorPriceBand": {
              "type": "object",
              "properties": {
                "maxUsd": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Protected band upper bound in USD."
                },
                "minUsd": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Protected band lower bound in USD."
                }
              },
              "description": "Optional original market anchor band selector.",
              "additionalProperties": false
            }
          },
          "description": "Preview selector.",
          "additionalProperties": false
        },
        "marketplaceScope": {
          "anyOf": [
            {
              "type": "string",
              "const": "all",
              "description": "Apply across all supported marketplaces."
            },
            {
              "type": "object",
              "required": [
                "channels"
              ],
              "properties": {
                "channels": {
                  "type": "array",
                  "items": {
                    "enum": [
                      "ebay",
                      "tcg",
                      "manapool",
                      "shopify",
                      "cardtrader"
                    ],
                    "type": "string"
                  },
                  "maxItems": 5,
                  "minItems": 1,
                  "description": "Specific marketplace channels for this amendment."
                }
              },
              "additionalProperties": false
            }
          ],
          "description": "Preview marketplace scope."
        }
      },
      "description": "Draft amendment; provide this or amendmentId.",
      "additionalProperties": false
    },
    "amendmentId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved amendment id from a prior amendment read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_amendment_preview_status

Read one pricing amendment preview job's bounded status and per-channel customer impacts. It returns counts, quantities, delta totals, timestamps, missing evidence and limitations. It never publishes or reprices.

read-only

Argument	Type	Description
jobId*	string	The preview job id returned by spellbook_pricing_amendment_preview. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "jobId"
  ],
  "properties": {
    "jobId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The preview job id returned by spellbook_pricing_amendment_preview. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_amendment_update

Update selected fields on one saved pricing amendment and return saved readback. Omitted fields preserve existing values, including server-owned demand behavior. The update does not publish or trigger repricing.

destructive

Argument	Type	Description
mode	object	Replacement absolute multiplier and optional protected band.
name	string	Replacement seller-selected name.
notes	any	Replacement notes; null clears notes.
enabled	boolean	Replacement enabled state.
priority	integer	Replacement precedence priority.
selector	object	Replacement bounded selector.
amendmentId*	string	The exact saved amendment id from a prior amendment read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
marketplaceScope

spellbook_pricing_amendments_list

List bounded seller pricing amendments with selector, marketplace scope, absolute multiplier, protected band, enabled state, priority and timestamps. It returns a cursor plus missing evidence and limitations.

read-only

Argument	Type	Description
limit	integer	Maximum amendments to return, 1 to 100. Omit for 50.
cursor	string	Opaque cursor from a prior list response. Omit for the first page.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum amendments to return, 1 to 100. Omit for 50."
    },
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque cursor from a prior list response. Omit for the first page."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_decision_explain

Read one seller listing's recorded pricing evidence for one marketplace. Returns the last recorded ask, market anchor, safe price effect, decision timestamps and whether the evidence is observed, recorded, projected or missing. Call this when a seller asks what price was saved or what evidence supports it, then use the seller controls tools when they want to inspect or change a setting. It never claims a remote marketplace ask is current without a remote observation timestamp.

read-only

Argument	Type	Description
itemId*	string	The exact Item id, from a prior spellbook_inventory_items_query. Required.
channel*	string	Which marketplace listing to explain. Required, because the same copy carries a different ask per channel.
workspaceId*	string	The workspace that owns the listing. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "itemId",
    "channel"
  ],
  "properties": {
    "itemId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact Item id, from a prior spellbook_inventory_items_query. Required."
    },
    "channel": {
      "enum": [
        "tcg",
        "ebay",
        "manapool",
        "cardtrader",
        "shopify"
      ],
      "type": "string",
      "description": "Which marketplace listing to explain. Required, because the same copy carries a different ask per channel."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the listing. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_profile_activate

Activate one seller-selected pricing profile and return its saved readback plus resulting active profile id. The first profile remains inactive until this explicit call. Activation does not publish or trigger repricing.

destructive

Argument	Type	Description
profileId*	string	The exact saved pricing profile id from a prior pricing profile read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "profileId"
  ],
  "properties": {
    "profileId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved pricing profile id from a prior pricing profile read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_profile_create

Create one seller pricing profile from a seller-selected name and explicit baseline multiplier and floor, with optional dollar offset, ordinary channel overrides, or a fixed equal-probability eBay base-price trial. A trial requires an explicit experiment id, positive allocation epoch and two different seller-selected multipliers. Returns saved profile and pin readback. It does not activate, publish or immediately reprice.

Argument	Type	Description
mult*	number	Explicit baseline market multiplier. Required.
name*	string	Seller-selected profile name. Required.
floor*	number	Explicit baseline floor in USD. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
marketOffsetUsd	number	Optional baseline dollar adjustment.
channelOverrides	object	Seller-approved overrides by marketplace channel. Omit when none are needed.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "name",
    "mult",
    "floor"
  ],
  "properties": {
    "mult": {
      "type": "number",
      "description": "Explicit baseline market multiplier. Required.",
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Seller-selected profile name. Required."
    },
    "floor": {
      "type": "number",
      "minimum": 0,
      "description": "Explicit baseline floor in USD. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "marketOffsetUsd": {
      "type": "number",
      "maximum": 1000,
      "minimum": -1000,
      "description": "Optional baseline dollar adjustment."
    },
    "channelOverrides": {
      "type": "object",
      "required": [
        "ebay",
        "tcg",
        "manapool",
        "shopify",
        "cardtrader"
      ],
      "description": "Seller-approved overrides by marketplace channel. Omit when none are needed.",
      "propertyNames": {
        "enum": [
          "ebay",
          "tcg",
          "manapool",
          "shopify",
          "cardtrader"
        ],
        "type": "string"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "mult": {
            "type": "number",
            "description": "Optional channel multiplier override.",
            "exclusiveMinimum": 0
          },
          "floor": {
            "type": "number",
            "minimum": 0,
            "description": "Optional channel floor in USD."
          },
          "valueBands": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "minUsd",
                "mult"
              ],
              "properties": {
                "mult": {
                  "type": "number",
                  "description": "Seller multiplier for this value band. Required.",
                  "exclusiveMinimum": 0
                },
                "floor": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Seller minimum price in USD for this value band. Omit to inherit the profile floor."
                },
                "label": {
                  "type": "string",
                  "maxLength": 50,
                  "minLength": 1,
                  "description": "Seller label for this ordinary market-value band. Omit when unlabeled."
                },
                "maxUsd": {
                  "type": "number",
                  "description": "Exclusive upper market value in USD. Omit for no upper bound.",
                  "exclusiveMinimum": 0
                },
                "minUsd": {
                  "type": "number",
                  "minimum": 0,
                  "description": "Inclusive lower market value in USD. Required."
                },
                "marketOffsetUsd": {
                  "type": "number",
                  "maximum": 1000,
                  "minimum": -1000,
                  "description": "Seller dollar adjustment after the market multiplier. Omit for no adjustment."
                }
              },
              "additionalProperties": false
            },
            "maxItems": 8,
            "description": "Optional ordinary market-value bands for this channel."
          },
          "basePriceTrial": {
            "type": "object",
            "required": [
              "enabled",
              "experimentId",
              "allocationEpoch",
              "controlMultiplier",
              "treatmentMultiplier"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Explicitly enable or disable the fixed trial."
              },
              "experimentId": {
                "type": "string",
                "maxLength": 100,
                "minLength": 1,
                "description": "Seller-selected stable experiment id."
              },
              "allocationEpoch": {
                "type": "integer",
                "maximum": 9007199254740991,
                "description": "Positive revision for this trial configuration; assignment stays stable for the experiment id. Use a new experimentId to create a new allocation.",
                "exclusiveMinimum": 0
              },
              "controlMultiplier": {
                "type": "number",
                "maximum": 20,
                "description": "Seller-selected control market multiplier.",
                "exclusiveMinimum": 0
              },
              "treatmentMultiplier": {
                "type": "number",
                "maximum": 20,
                "description": "Seller-selected treatment market multiplier; must differ while enabled.",
                "exclusiveMinimum": 0
              }
            },
            "description": "Optional fixed equal-probability eBay base-price trial. Seller supplies both multipliers; this is not adaptive.",
            "additionalProperties": false
          },
          "marketOffsetUsd": {
            "type": "number",
            "maximum": 1000,
            "minimum": -1000,
            "description": "Optional channel dollar adjustment."
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

spellbook_pricing_profile_get

Read one seller pricing profile's approved multiplier, floor, dollar offset, ordinary value bands, channel overrides, and any configured fixed eBay base-price trial, then report active state and channel pin facts. Call it before an update or activation.

read-only

Argument	Type	Description
profileId*	string	The exact saved pricing profile id from a prior pricing profile read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "profileId"
  ],
  "properties": {
    "profileId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved pricing profile id from a prior pricing profile read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_pricing_profile_update

Update selected seller-approved fields on one pricing profile and return saved profile and pin readback. Omitted fields stay unchanged. Null clears one channel override or only its eBay base-price trial.

destructive

Argument	Type	Description
mult	number	Replacement baseline multiplier.
name	string	Replacement seller-selected profile name.
floor	number	Replacement baseline floor in USD.
profileId*	string	The exact saved pricing profile id from a prior pricing profile read. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
marketOffsetUsd	number	Replacement baseline dollar adjustment.
channelOverrides	object	Selected per-channel overrides; omit to preserve all, null to clear one channel entry.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "profileId"
  ],
  "properties": {
    "mult": {
      "type": "number",
      "description": "Replacement baseline multiplier.",
      "exclusiveMinimum": 0
    },
    "name": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "Replacement seller-selected profile name."
    },
    "floor": {
      "type": "number",
      "minimum": 0,
      "description": "Replacement baseline floor in USD."
    },
    "profileId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved pricing profile id from a prior pricing profile read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "marketOffsetUsd": {
      "type": "number",
      "maximum": 1000,
      "minimum": -1000,
      "description": "Replacement baseline dollar adjustment."
    },
    "channelOverrides": {
      "type": "object",
      "required": [
        "ebay",
        "tcg",
        "manapool",
        "shopify",
        "cardtrader"
      ],
      "description": "Selected per-channel overrides; omit to preserve all, null to clear one channel entry.",
      "propertyNames": {
        "enum": [
          "ebay",
          "tcg",
          "manapool",
          "shopify",
          "cardtrader"
        ],
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "mult": {
                "anyOf": [
                  {
                    "type": "number",
                    "exclusiveMinimum": 0
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Channel multiplier override; null clears only this override."
              },
              "floor": {
                "anyOf": [
                  {
                    "type": "number",
                    "minimum": 0
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Channel floor override; null clears only this override."
              },
              "valueBands": {
                "anyOf": [
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "minUsd",
                        "mult"
                      ],
                      "properties": {
                        "mult": {
                          "type": "number",
                          "description": "Seller multiplier for this value band. Required.",
                          "exclusiveMinimum": 0
                        },
                        "floor": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Seller minimum price in USD for this value band. Omit to inherit the profile floor."
                        },
                        "label": {
                          "type": "string",
                          "maxLength": 50,
                          "minLength": 1,
                          "description": "Seller label for this ordinary market-value band. Omit when unlabeled."
                        },
                        "maxUsd": {
                          "type": "number",
                          "description": "Exclusive upper market value in USD. Omit for no upper bound.",
                          "exclusiveMinimum": 0
                        },
                        "minUsd": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Inclusive lower market value in USD. Required."
                        },
                        "marketOffsetUsd": {
                          "type": "number",
                          "maximum": 1000,
                          "minimum": -1000,
                          "description": "Seller dollar adjustment after the market multiplier. Omit for no adjustment."
                        }
                      },
                      "additionalProperties": false
                    },
                    "maxItems": 8
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Channel value bands; null clears only this override."
              },
              "basePriceTrial": {
                "anyOf": [
                  {
                    "type": "object",
                    "required": [
                      "enabled",
                      "experimentId",
                      "allocationEpoch",
                      "controlMultiplier",
                      "treatmentMultiplier"
                    ],
                    "properties": {
                      "enabled": {
                        "type": "boolean",
                        "description": "Explicitly enable or disable the fixed trial."
                      },
                      "experimentId": {
                        "type": "string",
                        "maxLength": 100,
                        "minLength": 1,
                        "description": "Seller-selected stable experiment id."
                      },
                      "allocationEpoch": {
                        "type": "integer",
                        "maximum": 9007199254740991,
                        "description": "Positive revision for this trial configuration; assignment stays stable for the experiment id. Use a new experimentId to create a new allocation.",
                        "exclusiveMinimum": 0
                      },
                      "controlMultiplier": {
                        "type": "number",
                        "maximum": 20,
                        "description": "Seller-selected control market multiplier.",
                        "exclusiveMinimum": 0
                      },
                      "treatmentMultiplier": {
                        "type": "number",
                        "maximum": 20,
                        "description": "Seller-selected treatment market multiplier; must differ while enabled.",
                        "exclusiveMinimum": 0
                      }
                    },
                    "additionalProperties": false
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Optional fixed equal-probability eBay base-price trial; null clears only this trial."
              },
              "marketOffsetUsd": {
                "anyOf": [
                  {
                    "type": "number",
                    "maximum": 1000,
                    "minimum": -1000
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Channel dollar adjustment; null clears only this override."
              }
            },
            "additionalProperties": false
          },
          {
            "type": "null"
          }
        ]
      }
    }
  },
  "additionalProperties": false
}

spellbook_pricing_profiles_list

List seller-created pricing profiles by name and active state, plus the resulting active profile id. Call it before choosing a profile for detail, update, activation or channel pinning.

read-only

Argument	Type	Description
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_printings_search

Find an exact card printing before recording a physical copy or forming a price. Searches by name, and narrows with `set:<code>` plus a collector number in the same query string, for example "Pikachu set:sv2a 025/165". Pokemon searches can filter English or Japanese catalog rows. Returns each printing with its product identity, game, language, set code, collector number, rarity and available finishes. Read this first, because a card name alone does not identify a printing, and a wrong printing values the wrong card.

read-only

Argument	Type	Description
q*	string	Card name to search, optionally narrowed with `set:<code>` plus a collector number in the same string, e.g. "sol ring set:c21 263". Required.
game	string	Restrict the search to one game. Omit to search all enabled games.
page	integer	Page number of results, 1 to 20. Omit for the first page.
language	string	Restrict Pokemon results to English or Japanese catalog rows. Omit when language is unknown.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "q"
  ],
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Card name to search, optionally narrowed with `set:<code>` plus a collector number in the same string, e.g. \"sol ring set:c21 263\". Required."
    },
    "game": {
      "enum": [
        "mtg",
        "riftbound",
        "pokemon"
      ],
      "type": "string",
      "description": "Restrict the search to one game. Omit to search all enabled games."
    },
    "page": {
      "type": "integer",
      "maximum": 20,
      "minimum": 1,
      "description": "Page number of results, 1 to 20. Omit for the first page."
    },
    "language": {
      "enum": [
        "en",
        "ja"
      ],
      "type": "string",
      "description": "Restrict Pokemon results to English or Japanese catalog rows. Omit when language is unknown."
    }
  },
  "additionalProperties": false
}

spellbook_pull_work

Read a page of SpellBook's current fulfillment work, grouped by marketplace order. Each order carries its tray slot and card lines with bin, printing, condition, and state, including blocked reasons and ship-by evidence when available. Use when a seller asks what to pull or pack. Read spellbook_skill for fulfilling-orders before coaching the workflow; follow nextCursor until hasMore is false before summarizing the full returned workset. Use pending lines for the shared bin walk, then verify and pack each order separately.

read-only

Argument	Type	Description
limit	integer	Maximum complete order groups to return on this page, from 1 to 50. Omit for 20.
cursor	string	Opaque nextCursor from the previous page. Pass it unchanged to continue; omit for the first page.
marketplace	string	Filter to one marketplace, or use all for the combined bin walk. Omit for all.
workspaceId*	string	The seller-owned workspace to read, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum complete order groups to return on this page, from 1 to 50. Omit for 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "Opaque nextCursor from the previous page. Pass it unchanged to continue; omit for the first page."
    },
    "marketplace": {
      "enum": [
        "all",
        "tcgplayer",
        "ebay",
        "shopify",
        "manapool",
        "cardtrader"
      ],
      "type": "string",
      "description": "Filter to one marketplace, or use all for the combined bin walk. Omit for all."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller-owned workspace to read, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_purchase_incoming_record

Record single cards the customer bought on a marketplace that have not arrived yet, one row per exact printing with the quantity and the price paid per copy. Each copy is written as pending receipt under one order, so it counts as incoming and cannot be listed or sold until it is received. Returns the order's acquisitionSource, the copy count, the total cost and the bins the copies will go into. Use it right after the customer completes a marketplace checkout for singles found through spellbook_buy_targets or spellbook_singles_buylist_spreads. It never buys anything and moves no money. A card already in hand goes through spellbook_inventory_bin_ensure instead. When the package arrives, call spellbook_inventory_incoming_receive with the returned acquisitionSource.

Argument	Type	Description
rows*	array	The order's lines, one per exact printing, condition and finish. Required, at least one.
orderRef*	string	The marketplace's order number from the checkout confirmation. Required. The same order number groups every copy for receiving.
sellerName	string	The seller's store name on the marketplace, when the checkout shows one. Shown beside the order in the incoming list.
marketplace*	string	Where the order was placed. Required. Use other for any marketplace not listed.
workspaceId*	string	The workspace that bought the cards, from spellbook_workspaces_list. Required; writes only to this workspace.

spellbook_repeat_buyers

Read which of the signed-in seller's buyers ordered more than once, across every channel SpellBook syncs orders from, and what happened after a free card shipped in an order. Returns overview counts and shares, weekly returning-order shares overall and per channel, buyerList with each repeat buyer's display name, channels, order count, spend and first and last order dates, and recipients with each free card recipient's prior and later orders and a status of came_back, bought_before or first_order. Call it when a seller asks who their repeat customers are, how many buyers come back, which buyers buy on more than one marketplace, or what free card recipients did next. It reads every workspace the seller belongs to and takes no input.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_return_address

Read the signed-in seller's saved return address: the name, street line, and city-state-ZIP line SpellBook prints on shipping labels, plus the other settings stored beside it. profile is null when the seller never saved one. Read it before spellbook_return_address_save, so the agent can show the seller what is on file.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_return_address_save

Save the return address the seller gave, which SpellBook prints on shipping labels and which store setup counts as returnAddressSaved. It replaces only the name, street, and city-state-ZIP lines and keeps every other saved setting. Only the workspace owner may call it, and only with an address the seller stated. A seller who does not want to share a home address in chat can type it on a SpellBook page, which the limits name, so offer that page before you ask for the address. Call spellbook_store_setup_status afterwards to confirm returnAddressSaved.

destructive

Argument	Type	Description
name*	string	The name on the return address, such as the seller's name or store name, exactly as the seller gave it. Required.
street*	string	One street line, such as a house number and street, exactly as the seller gave it. Required.
workspaceId*	string	The workspace whose setup this address completes. The caller must own it. Required.
cityStateZip*	string	One line with city, state, and ZIP code, such as Springfield, IL 62701, exactly as the seller gave it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "name",
    "street",
    "cityStateZip"
  ],
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "The name on the return address, such as the seller's name or store name, exactly as the seller gave it. Required."
    },
    "street": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "One street line, such as a house number and street, exactly as the seller gave it. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose setup this address completes. The caller must own it. Required."
    },
    "cityStateZip": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "One line with city, state, and ZIP code, such as Springfield, IL 62701, exactly as the seller gave it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_returned_package_case

Read one exact returned-order case, its original order and contents, inspection and dispatch history, and every saved replacement document. Each document carries a newly signed short-lived download URL, so use this read again when an older link expires or after a reship is resolved. Historical preparations are labeled explicitly. This owner-scoped read changes no return, shipment, inventory, postage or marketplace state.

read-only

Argument	Type	Description
caseId*	string	The exact caseId from returned-order work or a record response. Required.
workspaceId*	string	The seller workspace that owns the returned order. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "caseId"
  ],
  "properties": {
    "caseId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact caseId from returned-order work or a record response. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller workspace that owns the returned order. Required."
    }
  },
  "additionalProperties": false
}

spellbook_returned_package_lookup

Find shipped orders by marketplace order id, order label, tracking number, pull session id, or part of a buyer name or street line, and read each exact order's shipment facts and newest return case. Use it when a package came back before calling spellbook_returned_package_record. A multi-order pull sheet returns separate exact-order matches, each with its own returnCase. Use externalOrderId to record one selected order from a shared sheet. Each match carries sessionId, marketplace, externalOrderId, buyerName, shippedAt, trackingNumber, destinationSummary, packed and unresolved line counts, and returnCase. Card names are omitted to keep maximum batch responses bounded. Returns one row per identifier with status matched, ambiguous or not_found, plus missingFields. After recording a returned order, read its exact contents with spellbook_returned_package_case and find its task in spellbook_returned_package_work.

read-only

Argument	Type	Description
identifiers*	array	Up to 50 values to look up, each a marketplace order id, order label, tracking number, pull session id, or part of a buyer name or street line. Required, at least one.
workspaceId*	string	The workspace that shipped the orders, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "identifiers"
  ],
  "properties": {
    "identifiers": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Up to 50 values to look up, each a marketplace order id, order label, tracking number, pull session id, or part of a buyer name or street line. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that shipped the orders, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_returned_package_record

Record that a shipped order returned to the seller unopened. Pass the sessionId and exact externalOrderId from spellbook_returned_package_lookup when the pull sheet has several orders. Each selected order gets one return case with unconfirmed contents and appears automatically in spellbook_returned_package_work. This records the seller-reported reason; it does not refund, change inventory, postage or a marketplace. Returns one row per selected order with status recorded, already_open or failed, caseId and errorCode.

Argument	Type	Description
sessionIds*	array	Up to 50 sessionId values from spellbook_returned_package_lookup. For a shared multi-order sheet, send exactly one sessionId with its matching externalOrderId. Required, at least one.
workspaceId*	string	The workspace that shipped the orders, from spellbook_workspaces_list. Required; writes only to this workspace.
returnReason*	string	Why the carrier returned the packages, applied to every session in this call. address_issue means the address was wrong or incomplete, and the reship then requires a corrected address. unclaimed_or_refused covers an unclaimed or refused letter. Use unknown when the return label gives no reason. Required.
idempotencyKey*	string	A key you choose for this batch, such as rts- followed by the order id. Required. Send the same key on a retry after a timeout. A new key on a session that already has an open case returns already_open.
externalOrderId

spellbook_returned_package_reship_dispatch

Explicitly record that the seller mailed a returned order using its current preparation. Choose tracked with the tracking number or stamped/untracked with no tracking number, and send mailingConfirmed true only after mailing. The case resolves and leaves active work; its original order shipment remains unchanged. SpellBook does not verify carrier acceptance, buy postage, contact the buyer, or update a marketplace.

Argument	Type	Description
caseId*	string	Exact return caseId from returned-order work. Required.
method*	string	Use tracked only with a supplied tracking number. Use untracked for stamped mail with no tracking number.
workspaceId*	string	The seller workspace from spellbook_workspaces_list. Required.
preparationId*	string	The current preparationId from returned-order work. A stale preparation is rejected.
idempotencyKey*	string	A caller-generated key retained across retries.
trackingNumber	string	Tracking printed on the replacement mailer. Required exactly when method is tracked.
expectedVersion

spellbook_returned_package_reship_prepare

Prepare the current reship address for a returned order recorded with spellbook_returned_package_record. Pass the caseId and correctedDestination for an address_issue return; other reported reasons can reuse the saved original destination. A preparation is saved and remains current across reads. The returned row includes preparationId and the order-specific address. This legacy CSV preparation buys no postage and changes no shipment, stock or marketplace state. For a new reship, use spellbook_returned_package_reship_print and spellbook_returned_package_reship_dispatch. The older tracking-completion operation remains only for compatibility.

Argument	Type	Description
cases*	array	Up to 50 cases to prepare. Required, at least one.
workspaceId*	string	The workspace that shipped the orders, from spellbook_workspaces_list. Required; writes only to this workspace.
idempotencyKey*	string	A key you choose for this batch. Required. Send the same key and cases on a retry after a timeout to read the first result back.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "idempotencyKey",
    "cases"
  ],
  "properties": {
    "cases": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "caseId"
        ],
        "properties": {
          "caseId": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "The caseId from spellbook_returned_package_record, or from returnCase in spellbook_returned_package_lookup. Required."
          },
          "correctedDestination": {
            "type": "object",
            "required": [
              "buyerName",
              "addressLine1",
              "city",
              "region",
              "postalCode",
              "country"
            ],
            "properties": {
              "city": {
                "type": "string",
                "maxLength": 200,
                "minLength": 1,
                "description": "The city. Required."
              },
              "region": {
                "type": "string",
                "maxLength": 100,
                "minLength": 1,
                "description": "The state or region code, such as CA. Required."
              },
              "country": {
                "type": "string",
                "maxLength": 2,
                "minLength": 2,
                "description": "The two-letter country code, such as US. Required."
              },
              "buyerName": {
                "type": "string",
                "maxLength": 200,
                "minLength": 1,
                "description": "The recipient's name as it goes on the label. Required."
              },
              "postalCode": {
                "type": "string",
                "maxLength": 40,
                "minLength": 1,
                "description": "The ZIP or postal code. Required."
              },
              "addressLine1": {
                "type": "string",
                "maxLength": 300,
                "minLength": 1,
                "description": "The street line. Required."
              },
              "addressLine2": {
                "type": "string",
                "maxLength": 300,
                "minLength": 1,
                "description": "The apartment, unit or suite line. Omit when there is none."
              }
            },
            "description": "The address to use for this reship export, from the marketplace order page. Required when the case's returnReason is address_issue. Omit it to use the stored address or TCGplayer packing slip. A supplied address applies only to this export and its new receipt; it never overwrites the shipment address.",
            "additionalProperties": false
          },
          "expectedPreparationId": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 200,
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "The current preparationId from spellbook_returned_package_work when changing a saved destination; send null for a first preparation. This rejects a stale edit."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Up to 50 cases to prepare. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that shipped the orders, from spellbook_workspaces_list. Required; writes only to this workspace."
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A key you choose for this batch. Required. Send the same key and cases on a retry after a timeout to read the first result back."
    }
  },
  "additionalProperties": false
}

spellbook_returned_package_reship_print

Create or recover the immutable replacement-address PDF for one returned-order task. Use the current preparationId from spellbook_returned_package_work or spellbook_returned_package_reship_prepare. The address label is available directly. A contents page is optional and separate from the intact-package happy path. The receipt identifies its exact order and preparation and includes a short-lived download URL. This prints no postage and does not mean the package was mailed.

Argument	Type	Description
caseId*	string	Exact return caseId from returned-order work. Required.
workspaceId*	string	The seller workspace from spellbook_workspaces_list. Required.
preparationId*	string	The current preparationId for this task. A stale preparation is rejected.
idempotencyKey*	string	A caller-generated key retained across retries. Reusing it returns the same immutable document receipt.
includeContents	boolean	Whether to append the original returned contents as a separate no-price page. Defaults to false; an intact package does not need to be opened.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "caseId",
    "preparationId",
    "idempotencyKey"
  ],
  "properties": {
    "caseId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact return caseId from returned-order work. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller workspace from spellbook_workspaces_list. Required."
    },
    "preparationId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The current preparationId for this task. A stale preparation is rejected."
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A caller-generated key retained across retries. Reusing it returns the same immutable document receipt."
    },
    "includeContents": {
      "type": "boolean",
      "description": "Whether to append the original returned contents as a separate no-price page. Defaults to false; an intact package does not need to be opened."
    }
  },
  "additionalProperties": false
}

spellbook_returned_package_reship_tracking

Compatibility operation for reships completed outside the new Pull Sessions flow. Records tracking evidence supplied by the seller and resolves the case with resolution reship. It does not prove that an operator explicitly confirmed mailing, and it must not be called by new file-import or print flows. New reships use spellbook_returned_package_reship_dispatch with an explicit tracked or stamped/untracked mailing confirmation.

Argument	Type	Description
matches*	array	Up to 50 pairs of caseId and tracking number. Required, at least one.
workspaceId*	string	The workspace that shipped the orders, from spellbook_workspaces_list. Required; writes only to this workspace.
idempotencyKey*	string	A key you choose for this batch. Required. Send the same key on a retry after a timeout.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "idempotencyKey",
    "matches"
  ],
  "properties": {
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "caseId",
          "trackingNumber"
        ],
        "properties": {
          "caseId": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "The caseId of a prepared reship. Required."
          },
          "trackingNumber": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "The tracking number printed on the new label. Required."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Up to 50 pairs of caseId and tracking number. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that shipped the orders, from spellbook_workspaces_list. Required; writes only to this workspace."
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A key you choose for this batch. Required. Send the same key on a retry after a timeout."
    }
  },
  "additionalProperties": false
}

spellbook_returned_package_work

List active returned-order tasks in a seller workspace. Each task includes an exact externalOrderId when one order is identified, plus original destination evidence, return reason, case version and current saved preparation including the corrected destination. Historical mixed-order cases stay visible as blocked inspection tasks without selecting a candidate. Use this after spellbook_returned_package_record or after reconnecting to resume the same task. The read does not change shipment, inventory, refund, postage or marketplace state.

read-only

Argument	Type	Description
q	string	Find an original order by order id, label, buyer, card name, pull-session id or tracking number. Requires at least two characters.
limit	integer	Maximum active return tasks to return, up to 50. Defaults to 20.
cursor	string	Opaque next-page cursor returned by a prior read. Omit for the first page.
marketplace	string	Limit tasks to one marketplace. Omit for all.
workspaceId*	string	The seller workspace from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 200,
      "minLength": 2,
      "description": "Find an original order by order id, label, buyer, card name, pull-session id or tracking number. Requires at least two characters."
    },
    "limit": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum active return tasks to return, up to 50. Defaults to 20."
    },
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque next-page cursor returned by a prior read. Omit for the first page."
    },
    "marketplace": {
      "enum": [
        "manapool",
        "tcgplayer",
        "ebay",
        "cardtrader"
      ],
      "type": "string",
      "description": "Limit tasks to one marketplace. Omit for all."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The seller workspace from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_riftbound_japanese_comparables

Read physical Japanese-language Riftbound observations, separate from English cards sold in Japan. Returns exact SKU language, finish, condition, price kind, source links, actual price capture timestamps, freshness policy, per-source eligible denominators and nullable acceptance rates. ManaPool is unsupported_game. Distinguishes unavailable, stale, completed eligible zero and accepted evidence. TCG Market is a provider statistic, not a completed sale or guaranteed resale proceeds. asOf is query time. An empty result never implies a market price of zero or proves market-wide coverage.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_sale_record

Record a sale of cards the seller's workspace holds that happened outside SpellBook's order intake, such as a local game store buy, an in-person trade, or a one-off marketplace sale SpellBook did not import. Names the exact printing, finish, condition, quantity and unit sale price. It marks that many copies sold, oldest first, closes the position so spellbook_inventory_holdings and spellbook_buy_outcome_report reflect it, and pulls those copies off every marketplace where they are still live. Returns the sold item ids and the holding after the sale.

destructive

Argument	Type	Description
qty*	integer	How many copies sold. Required.
note	string	A free-text note stored with the sale. Optional.
binId	string	Sell only copies from this bin. Omit to take the oldest copies from any bin.
finish*	string	The finish of the sold copies, matching the finish recorded in inventory. Pokemon supports nf (Normal/Unlimited), fo (Holofoil), rh (Reverse Holofoil), 1e (1st Edition) and 1e-fo (1st Edition Holofoil). Required.
orderId*	string	A stable reference for this sale, such as the buyer's order number or a receipt number. Required. A second call with the same orderId for the same printing, finish and condition returns the first sale with replayed true and sells nothing.

spellbook_screener

Screen Magic card printings by regular or foil price, foil/nonfoil premium, price change and 20 day band statistics in one call. For unusually high foil premiums, use mode=both and sort=premium with a declared regular-price floor. Premium sorts the dimensionless foilPrice/price multiple; the response retains both USD inputs. Read the matching foil-premium guide via spellbook_guides topic pricing and its returned resource URI for identity and interpretation limits. Some snapshots also carry optional printingCount, lastPrintedAt and reserved facts; absent fields stay unknown. For reprint interpretation, use spellbook_guides topic reprint-risk and read the returned resource URI; these facts supply no calibrated set-risk ranking. Each row carries reported printing identity (scryfallId, name, setCode, rarity), price, and change7d, change30d and change90d in percent. Its band fields: ma20 is the mean of the last 20 daily closes. bbPos is where today's close sits inside the 20 day Bollinger band, 0 at the lower band and 100 at the upper, and below 0 or above 100 outside it. bbWidth is the band's width as a percent of ma20. z20 is today's close minus ma20, in 20 day standard deviations. squeeze and squeezeRecent say whether the Bollinger band sat inside the Keltner channel today, or on any of the last 5 days. flatDays counts the days since the price last changed. swing30d is the typical 30 day move: the median absolute 30 day change, in percent, over the last 90 daily closes. Call it to answer "which cards sit near the bottom of their recent range", "which cards fell this month inside a 90 day rise", "which cards moved far past their usual size this month" or "which prices have gone quiet", then call spellbook_card_prices for one printing's per-source prices. Rows come back in the sort the caller names. Nothing is scored, labeled or chosen for you.

read-only

Argument	Type	Description
mode	string	Price mode. nonfoil uses regular prices for the price floor and ceiling; foil uses foil prices; both requires positive regular and foil inputs and uses the regular price bounds. Band and change30d_max/change90d_min/move_ratio_min fields remain regular-price statistics in every mode.

spellbook_sealed_deal_board

Read the Sealed Deal Board: sealed boxes and decks that third-party stores list, one row per product. Each row carries the store, productUrl, retailerPriceUsd, marketPrice (the product's TCGplayer market price, USD), anchorPriceUsd with anchorSource, tcgProductId, shippingPolicy and age stamps: firstSeenAt (the day the board first carried that product), firstSeenBasis, priceBeatenAt with priceBeatenFromUsd (the day its cheapest price fell at least 5% and at least $10 under its own trailing 30-day low), and recencyEventAt, the later of the two, so you can answer "what is new since <date>" without diffing the whole board. Filter by game and productType (for example booster_display); results come in pages of limit rows with nextCursor, which is null on the last page. A caller with no account, or without Investor access, gets the public preview the website shows: a few rows per currency with entitled false. A caller with Investor access gets the full board. Call spellbook_sealed_product_offers with a row's tcgProductId for every store's offer and the sold comparables. Rows arrive in the board's order. Compare retailerPriceUsd with marketPrice yourself; this returns facts and ranks nothing by recency or discount.

read-only

Argument	Type	Description
game	string	Restrict rows to one game: mtg, riftbound or pokemon. Omit to include all games.
limit	integer	Maximum deal rows per page, 1 to 50. Omit for the default of 15.
cursor	string	Opaque nextCursor from the previous page, passed back unchanged with the same game and productType. Omit to start from the first page.
productType	string

spellbook_sealed_intent_default_set

Set a workspace rule for future extension-captured sealed purchases. An exact game and productType wins over wildcard rules. Read spellbook_sealed_intent_defaults before and after; existing units keep their current marks.

destructive

Argument	Type	Description
game*	string	The game to match, or * for every game. Required.
intent*	string	The capture intent: open or hold. This does not physically open or list stock. Required.
productType*	string	The sealed product type to match, or * for every type. Required.
workspaceId*	string	The workspace whose rule to set. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "game",
    "productType",
    "intent"
  ],
  "properties": {
    "game": {
      "enum": [
        "mtg",
        "riftbound",
        "pokemon",
        "*"
      ],
      "type": "string",
      "description": "The game to match, or * for every game. Required."
    },
    "intent": {
      "enum": [
        "open",
        "hold"
      ],
      "type": "string",
      "description": "The capture intent: open or hold. This does not physically open or list stock. Required."
    },
    "productType": {
      "enum": [
        "booster_display",
        "collector_box",
        "commander_deck",
        "theme_deck",
        "planeswalker_deck",
        "starter_kit",
        "challenger_deck",
        "precon",
        "bundle",
        "prerelease_kit",
        "jumpstart",
        "secret_lair",
        "*"
      ],
      "type": "string",
      "description": "The sealed product type to match, or * for every type. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose rule to set. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_intent_defaults

Read a workspace's future sealed-purchase open or hold defaults. Call this before changing how extension-captured products are classified. These rows affect future captures only; spellbook_sealed_portfolio reports marks already on physical units.

read-only

Argument	Type	Description
workspaceId*	string	The workspace whose defaults to read. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose defaults to read. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_listing_pause

Remove one SpellBook-managed sealed listing from ManaPool or set its TCGplayer quantity to zero through the paired browser. Call spellbook_sealed_listing_preview first and pass its channel and intentRevision unchanged. A product with no saved SpellBook intent cannot be removed by this tool.

destructive

Argument	Type	Description
game	string	The product game. Defaults to mtg.
kind*	string	The sealed kind from the same portfolio row. Required.
boxId*	string	The exact TCGplayer sealed product id from the portfolio row. Required.
channel	string	Marketplace whose managed listing should be removed. Defaults to manapool.
language	string	The product language code. Defaults to EN.
workspaceId*	string	The workspace that owns the listing. Required.
idempotencyKey*	string	A unique request key for this removal, such as a new UUID. If the result is uncertain, preview current state before deciding on another pause. Required.

spellbook_sealed_listing_preview

Preview one sealed listing on ManaPool or TCGplayer without publishing. Returns the proposed quantity and ask, any current offer, TCG publisher readback state, stock and intent revisions, and blockers. For TCGplayer, the first call may queue an exact seller-grid SKU read; call again after the paired extension finishes. After submitting, call preview again: publisher.state live confirms an offer, and removed confirms a zero-quantity removal. Pass this preview's channel, ask, and revisions to spellbook_sealed_listing_submit.

read-only

Argument	Type	Description
cap	integer	The most units to offer at once. Omit to offer every eligible unit.
game	string	The game of the product. Defaults to mtg.
kind*	string	The sealed kind, the kind on the same spellbook_sealed_portfolio row. Required, because units are counted by kind and boxId together.
boxId*	string	The TCGplayer product id of the sealed product, the boxId on a spellbook_sealed_portfolio row. Required.
channel	string	Marketplace to preview. Defaults to manapool.
floorUsd	number	undercut only. The lowest ask in USD the rule may choose. Omit to use catalog market times floorMarketFraction.

spellbook_sealed_listing_submit

Submit one sealed product listing to ManaPool or TCGplayer at the exact quantity and ask shown by spellbook_sealed_listing_preview. Pass the same channel and product arguments, plus proposed.stockRevision, proposed.askUsd, and intentRevision unchanged. ManaPool submits directly. TCGplayer queues the paired browser writer. A queued TCG write is pending until an exact seller-grid readback confirms it.

destructive

Argument	Type	Description
cap	integer	The most units to offer at once. Omit to offer every eligible unit.
game	string	The game of the product. Defaults to mtg.
kind*	string	The sealed kind, the kind on the same spellbook_sealed_portfolio row. Required, because units are counted by kind and boxId together.
boxId*	string	The TCGplayer product id of the sealed product, the boxId on a spellbook_sealed_portfolio row. Required.
channel	string	Marketplace to submit to. Must match the preview. Defaults to manapool.
floorUsd	number	undercut only. The lowest ask in USD the rule may choose. Omit to use catalog market times floorMarketFraction.
language

spellbook_sealed_portfolio

Read a seller's sealed boxes, packs and cases, with quantity, cost basis, market price, heldQuantity, openIntentQuantity, acquisitionSource and workspaceId for each purchase entry. Call this to reconcile physical sealed stock before listing or opening it. Recovered components can have unknown allocated cost basis and an approximate recovery date. A hold differs from an actual opening; call spellbook_sealed_portfolio_hold_set to correct a holding mark.

read-only

Argument	Type	Description
workspaceId*	string	The workspace whose sealed positions to read, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose sealed positions to read, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_portfolio_hold_set

Mark every still-sealed unit in one purchase entry as a long-term hold, or release that hold. A hold keeps physical inventory and market value but excludes those units from sealed listing. Read spellbook_sealed_portfolio before and after to check heldQuantity.

Argument	Type	Description
hold*	boolean	True excludes live units from listing; false makes them eligible again. Required.
entryId*	string	The exact purchase entryId from spellbook_sealed_portfolio, including the SEALED# prefix when present. Required.
workspaceId*	string	The workspace that owns the entry. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "entryId",
    "hold"
  ],
  "properties": {
    "hold": {
      "type": "boolean",
      "description": "True excludes live units from listing; false makes them eligible again. Required."
    },
    "entryId": {
      "type": "string",
      "pattern": "^(?:[A-Za-z0-9_-]{1,64}|SEALED#[A-Za-z0-9_-]{1,64})$",
      "description": "The exact purchase entryId from spellbook_sealed_portfolio, including the SEALED# prefix when present. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the entry. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_portfolio_open

Record that an exact quantity of sealed boxes or packs has already been physically opened. Use the entryId from spellbook_sealed_portfolio and read the returned counts; the same entryId and quantity safely replay after a timeout. The historical opening date stays unknown, and recordedAt means when SpellBook recorded the status. No singles are created.

destructive

Argument	Type	Description
entryId*	string	The exact sealed purchase entryId from spellbook_sealed_portfolio. Required.
quantity*	integer	Exact count of units already opened from this entry. Required.
workspaceId*	string	The workspace that owns the sealed entry. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "entryId",
    "quantity"
  ],
  "properties": {
    "entryId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The exact sealed purchase entryId from spellbook_sealed_portfolio. Required."
    },
    "quantity": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "description": "Exact count of units already opened from this entry. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the sealed entry. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_portfolio_open_intent_clear

Clear the plan to open every still-sealed unit in one purchase entry. Call this when spellbook_sealed_portfolio shows openIntentQuantity for stock the seller intends to keep sealed; then read the portfolio again. This preserves the units and any holding mark.

destructive

Argument	Type	Description
entryId*	string	The exact purchase entryId from spellbook_sealed_portfolio. Required.
workspaceId*	string	The workspace that owns the entry. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "entryId"
  ],
  "properties": {
    "entryId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The exact purchase entryId from spellbook_sealed_portfolio. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the entry. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_portfolio_receive

Mark one incoming sealed display purchase entry as physically received after the seller confirms its arrival. Call spellbook_sealed_portfolio first to identify the incoming entry, then read it again to confirm owned status. This preserves its holding mark and opening plan.

destructive

Argument	Type	Description
entryId*	string	The exact incoming display entryId from spellbook_sealed_portfolio. Required.
workspaceId*	string	The workspace that owns the incoming entry. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "entryId"
  ],
  "properties": {
    "entryId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,64}$",
      "description": "The exact incoming display entryId from spellbook_sealed_portfolio. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that owns the incoming entry. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_portfolio_record

Record one sealed acquisition the customer has already made, so the buy can be scored later against what it cost. Names the catalog boxId, the quantity, the unit price paid as a decimal string, and the acquisition date. Use it after a seller buys a box, pack or case found through spellbook_sealed_deal_board. It records a purchase that happened; it never buys anything and moves no money.

Argument	Type	Description
boxId*	string	Exact sealed catalog product id, from spellbook_sealed_product_search or spellbook_sealed_deal_board. An id the catalog does not hold is refused. Required.
quantity*	integer	How many units of this product were bought. Required.
salesTaxUsd	string	Sales tax paid on the whole order in USD, as a decimal string. Optional.
workspaceId*	string	The workspace to record this sealed buy in, from spellbook_workspaces_list. Required.
acquisitionDate*	string	The date the buy happened, as YYYY-MM-DD. Required, and it sets which day's modeled EV the purchase is scored against.
acquisitionPrice*	string	Price paid PER UNIT in USD, as a decimal string such as "114.99". Not the order total. Required.

spellbook_sealed_product_offers

Inspect one exact TCG product ID's sealed offers and their source times. Each offer includes the exact store listing, its local price, the crawl's actionability observation, and the selected exit comparable with its evidence date. Checkout shipping, tax, and available quantity are explicitly unknown until checked with the store. Opening EV is not intact resale value. Empty title or null computedAt can mean missing snapshot.

read-only

Argument	Type	Description
region	string	Restrict retail references to one currency region: US, CA, NZ or All. Omit for all.
tcgProductId*	string	Exact TCGplayer product id for this sealed product, digits only. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "tcgProductId"
  ],
  "properties": {
    "region": {
      "enum": [
        "US",
        "CA",
        "NZ",
        "All"
      ],
      "type": "string",
      "description": "Restrict retail references to one currency region: US, CA, NZ or All. Omit for all."
    },
    "tcgProductId": {
      "type": "string",
      "pattern": "^\\d{1,12}$",
      "description": "Exact TCGplayer product id for this sealed product, digits only. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sealed_product_search

Search sealed catalog identity and available offer records by a third-party listing's name, set and product type. catalogMatches covers boxes, packs and cases, returning exact product IDs, kind, physicalLanguage, form, contentsState, intact marketPrice with marketPriceObservedAt, coverage (priceState, modelState, evState, totalEv, missingInput), and a cached pokemonEvDisplay when available. A Pokemon tier partial gives a numeric priced-component value with valueScope and missingFields; it may include an exact identified promo. It is not full product EV or a lower bound and must not be ranked as one. Its marginal rate sensitivity is not an opening percentile or joint confidence interval. A zero-observation rare-tail gross bound, when present, uses the stated maximum copies per pack, representative independent packs and frozen subtype prices; it ignores displaced card value and is not added to the central partial value. products returns deal rows with modeled totalEV and offer evidence when supported. Call spellbook_sealed_product_offers with a deal row's tcgProductId for retail references, available sold comparables and freshness. This tool carries no per-pack distribution; for how many packs until opening is likely profitable, how swingy a box is, or what share of packs beat the pack price, call spellbook_box_ev_rankings with q set to the product name. The backend chooses the public or entitled response. A public response sets teaser true and returns fewer deal rows.

read-only

Argument	Type	Description
q	string	Free-text product name search. Omit to browse without a name filter.
game	string	Restrict results to one game: mtg, riftbound or pokemon. Omit for a mixed-game search.
limit	integer	Maximum rows to return, 1 to 100. Omit for the default of 20.

spellbook_sealed_recovered_component_record

Record sealed packs recovered from already-opened products, without adding a new purchase or guessing their share of the parent product's cost. This bounded intake accepts the confirmed Aetherdrift Box Topper and Modern Horizons 3 Collector Booster Sample Pack products. It records zero incremental cash, keeps parent basis unallocated, marks recovery timing approximate, and returns persisted-row readback. Reuse requestId unchanged after a timeout.

Argument	Type	Description
hold*	boolean	True marks these units as held from listing; false leaves them unheld. Required.
quantity*	integer	How many recovered units to record: up to 11 for product 618698, or exactly 1 for product 579917. Required.
productId*	string	Exact TCG sealed pack product id: 618698 for Aetherdrift Box Topper, or 579917 for Modern Horizons 3 Collector Booster Sample Pack. Required.
requestId*	string	Stable idempotency key for this recovery entry. Reuse this exact value to retry. Required.
workspaceId*	string	The workspace to add recovered sealed components to. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "productId",
    "quantity",
    "requestId",
    "hold"
  ],
  "properties": {
    "hold": {
      "type": "boolean",
      "description": "True marks these units as held from listing; false leaves them unheld. Required."
    },
    "quantity": {
      "type": "integer",
      "maximum": 11,
      "minimum": 1,
      "description": "How many recovered units to record: up to 11 for product 618698, or exactly 1 for product 579917. Required."
    },
    "productId": {
      "enum": [
        "579917",
        "618698"
      ],
      "type": "string",
      "description": "Exact TCG sealed pack product id: 618698 for Aetherdrift Box Topper, or 579917 for Modern Horizons 3 Collector Booster Sample Pack. Required."
    },
    "requestId": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,100}$",
      "description": "Stable idempotency key for this recovery entry. Reuse this exact value to retry. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to add recovered sealed components to. Required."
    }
  },
  "additionalProperties": false
}

spellbook_seller_plan_checkout_link

Get the checkout page for a seller-chosen Store plan on one workspace: a Stripe page, or a Shopify charge approval page for a workspace that installed the SpellBook Finance Shopify app and has no Stripe subscription. Read spellbook_workspace_plan_status first. Skip checkout when sellerToolsUnlocked comes from an active Store plan, person-level Pro, or admin access. The 10,000-unit allowance is soft; do not suggest checkout solely because observed usage exceeds it. Offer paid Store features only when the seller chooses them. Give the returned URL to the seller to enter payment details at Stripe, then re-read plan status to observe its stored state; that status cannot prove payment settled. It refuses a workspace whose plan is already active.

Argument	Type	Description
interval*	string	The billing interval the seller chose: monthly or annual. Required.
workspaceId*	string	The workspace the Store plan is for. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "interval"
  ],
  "properties": {
    "interval": {
      "enum": [
        "monthly",
        "annual"
      ],
      "type": "string",
      "description": "The billing interval the seller chose: monthly or annual. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the Store plan is for. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_singles_buylist_spreads

Investigate Magic TCGplayer NM acquisitions against Card Kingdom buylist payout scenarios. Preserve source timestamps, finish, stock, grading scenarios, and queue degradation; spread is not net realized profit.

read-only

Argument	Type	Description
sets	string	Exact set code(s) to filter to. Omit to include every set.
limit	integer	Maximum rows to return, 1 to 200. Omit for the default of 20.
cursor	string	Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page.
isFoil	boolean	True restricts to foil rows, false to non-foil. Omit to include both.
rarity	string	Exact rarity to filter to. Omit to include every rarity.
sortBy	string	Which field ranks the rows. Omit for the default order.
sortDir	string	Sort direction for sortBy. Omit for the default direction.
minCkQty	integer	Minimum Card Kingdom buylist quantity a row must have. Omit for no floor.

spellbook_skill

Read the step-by-step procedure SpellBook Finance wrote for a whole customer task, in full. getting-started takes a new seller from sign-in through supplies, bin labels, a first tracked card, and connected marketplaces. buy-loop covers inspecting buy facts and recording what happened. collection-buying covers screening a Marketplace or local Pokémon lot, the questions to ask the seller, per-name printing checks, and recording the buy. physical-placement covers moving one item to a bin and verifying it. fulfilling-orders covers where an order lands, the bin walk that finds each sold card, and who packs, labels, and confirms shipped. Read the matching procedure before the first call of that task. Omit name to list every procedure with its title.

read-only

Argument	Type	Description
name	string	The procedure to read in full. Omit to list every procedure with its title.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "name": {
      "enum": [
        "getting-started",
        "buy-loop",
        "collection-buying",
        "physical-placement",
        "fulfilling-orders"
      ],
      "type": "string",
      "description": "The procedure to read in full. Omit to list every procedure with its title."
    }
  },
  "additionalProperties": false
}

spellbook_sku_exact_price_lock_clear

Clear one seller SKU's unprotected exact-price lock by exact printing, finish and condition. Seller-protected locks refuse agent removal. Call spellbook_sku_price_controls first to inspect protection; the saved readback confirms a successful clear with a null lock.

destructive

Argument	Type	Description
finish*	string	The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required.
condition*	string	The exact physical condition for the SKU. Required.
scryfallId*	string	The exact Scryfall printing id. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "scryfallId",
    "finish",
    "condition"
  ],
  "properties": {
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "The exact physical condition for the SKU. Required."
    },
    "scryfallId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact Scryfall printing id. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sku_exact_price_lock_set

Set one seller SKU's unprotected exact-price lock and return its saved readback. Identify the exact printing, finish and condition. A seller-protected lock refuses agent changes. Call spellbook_sku_price_controls first to inspect protection. Saving a lock does not publish or trigger repricing.

destructive

Argument	Type	Description
finish*	string	The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required.
priceUsd*	number	The seller-selected exact locked price in USD. Required.
condition*	string	The exact physical condition for the SKU. Required.
scryfallId*	string	The exact Scryfall printing id. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "scryfallId",
    "finish",
    "condition",
    "priceUsd"
  ],
  "properties": {
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required."
    },
    "priceUsd": {
      "type": "number",
      "maximum": 1000000,
      "description": "The seller-selected exact locked price in USD. Required.",
      "exclusiveMinimum": 0
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "The exact physical condition for the SKU. Required."
    },
    "scryfallId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact Scryfall printing id. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sku_minimum_floor_clear

Clear one seller SKU's minimum floor by exact printing, finish and condition. Returns the saved controls readback, so the agent can confirm the floor is null.

destructive

Argument	Type	Description
finish*	string	The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required.
condition*	string	The exact physical condition for the SKU. Required.
scryfallId*	string	The exact Scryfall printing id. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "scryfallId",
    "finish",
    "condition"
  ],
  "properties": {
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "The exact physical condition for the SKU. Required."
    },
    "scryfallId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact Scryfall printing id. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sku_minimum_floor_set

Set one seller SKU's minimum sell price and return its saved readback. Identify the exact printing, finish and condition. A floor raises computed prices up to the floor; it does not make an exact ask and does not trigger repricing.

destructive

Argument	Type	Description
finish*	string	The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required.
condition*	string	The exact physical condition for the SKU. Required.
scryfallId*	string	The exact Scryfall printing id. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.
minSellPriceUsd*	number	The seller-selected minimum sell price in USD. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "scryfallId",
    "finish",
    "condition",
    "minSellPriceUsd"
  ],
  "properties": {
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "The exact physical condition for the SKU. Required."
    },
    "scryfallId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact Scryfall printing id. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "minSellPriceUsd": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 0,
      "description": "The seller-selected minimum sell price in USD. Required."
    }
  },
  "additionalProperties": false
}

spellbook_sku_price_controls

Read one seller SKU's exact minimum floor and exact-price lock by printing, finish and condition. Returns saved values, timestamps, all-marketplaces lock scope and whether the seller protected the lock from agent changes. Call it before changing a floor or lock, then read it again after a write.

read-only

Argument	Type	Description
finish*	string	The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required.
condition*	string	The exact physical condition for the SKU. Required.
scryfallId*	string	The exact Scryfall printing id. Required.
workspaceId*	string	The workspace the seller selected. The caller must own it. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "scryfallId",
    "finish",
    "condition"
  ],
  "properties": {
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The exact finish for the SKU: nf, fo, etched, surge, rh, 1e or 1e-fo. Required."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "The exact physical condition for the SKU. Required."
    },
    "scryfallId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The exact Scryfall printing id. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    }
  },
  "additionalProperties": false
}

spellbook_store_setup_status

Read one workspace's store setup facts and seller-activation projection: which setup facts are true, the current phase, nextAction and blockers, each channel's automation mode and meaning, and server evidence for the first verified eBay and ManaPool listings in autoListing. Use autoListing.ebay.firstVerifiedListing or autoListing.manapool.firstVerifiedListing to decide whether that channel reached the verified-first-listing step; read its verificationPending field when proof is still absent. Baseline quantity remains marketplace evidence, not physical stock. Call this for a seller's setup status or after an automation-policy change.

read-only

Argument	Type	Description
workspaceId*	string	The workspace to read setup status for. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to read setup status for. Required."
    }
  },
  "additionalProperties": false
}

spellbook_support_report

Store one minimal customer failure report. Generate a fresh ULID submissionId and reuse the exact request for retries within 24 hours. Reports are accepted only after storage. No raw diagnostics, conversations, secrets, or customer identity. Available to authenticated Free customers, including paid-access denials. A report reaches no person.

Argument	Type	Description
errorCode*	string	Which closed error code best matches the failure. Required.
operation*	string	Which SpellBook operation failed. Required, one of the closed operation names.
occurredAt*	string	ISO-8601 timestamp of when the failure occurred. Required.
submissionId*	string	A fresh ULID for this report. Reuse the exact same value and request body to retry within 24 hours; a new value starts a new report.
clientVersion*	string	This client's semantic version, e.g. "1.2.3". Required.
correlationId	string	A correlation id from a prior response, if one was returned. Omit when none was given.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "submissionId",
    "operation",
    "clientVersion",
    "occurredAt",
    "errorCode"
  ],
  "properties": {
    "errorCode": {
      "enum": [
        "login_required",
        "access_denied",
        "invalid_input",
        "invalid_upstream_response",
        "upstream_http_error",
        "upstream_timeout",
        "upstream_unavailable",
        "upstream_response_too_large",
        "auth_unavailable",
        "invalid_token_response",
        "credential_store_busy",
        "credential_store_unavailable",
        "client_failure",
        "request_cancelled",
        "client_type_error",
        "client_range_error",
        "client_reference_error"
      ],
      "type": "string",
      "description": "Which closed error code best matches the failure. Required."
    },
    "operation": {
      "enum": [
        "spellbook_workspaces_list",
        "spellbook_buy_targets",
        "spellbook_buy_outcome_report",
        "spellbook_entitlements",
        "spellbook_singles_buylist_spreads",
        "spellbook_credit_conversion_candidates",
        "spellbook_credit_resale_assessment",
        "spellbook_sealed_product_search",
        "spellbook_sealed_product_offers",
        "spellbook_sealed_deal_board",
        "spellbook_customer_evidence_record",
        "spellbook_customer_evidence_get",
        "spellbook_customer_evidence_list",
        "spellbook_collection_buying_record",
        "spellbook_collection_buying_get",
        "spellbook_collection_buying_list",
        "spellbook_inventory_items_query",
        "spellbook_inventory_location_confirm",
        "spellbook_inventory_holdings",
        "spellbook_sealed_portfolio",
        "spellbook_sealed_portfolio_record",
        "spellbook_sealed_portfolio_hold_set",
        "spellbook_sealed_portfolio_open_intent_clear",
        "spellbook_sealed_portfolio_receive",
        "spellbook_sealed_portfolio_open",
        "spellbook_sealed_recovered_component_record",
        "spellbook_sealed_intent_defaults",
        "spellbook_sealed_intent_default_set",
        "spellbook_sale_record",
        "spellbook_agent_gap_report",
        "spellbook_support_report",
        "spellbook_store_setup_status",
        "spellbook_guides",
        "spellbook_skill",
        "spellbook_printings_search",
        "spellbook_inventory_bin_ensure",
        "spellbook_inventory_import_csv",
        "spellbook_inventory_precon_import",
        "spellbook_purchase_incoming_record",
        "spellbook_inventory_incoming",
        "spellbook_returned_package_lookup",
        "spellbook_returned_package_record",
        "spellbook_returned_package_reship_prepare",
        "spellbook_returned_package_reship_tracking",
        "spellbook_returned_package_case",
        "spellbook_inventory_incoming_receive",
        "spellbook_movers",
        "spellbook_buyouts",
        "spellbook_screener",
        "spellbook_card_desk",
        "spellbook_card_prices",
        "spellbook_ath_observations",
        "spellbook_card_buylist",
        "spellbook_pokemon_market_analytics",
        "spellbook_pokemon_ath",
        "spellbook_pokemon_arbitrage_spreads",
        "spellbook_deck_contents",
        "spellbook_deck_import_limitless",
        "spellbook_pokemon_metagame_overview",
        "spellbook_pokemon_metagame_archetype",
        "spellbook_pokemon_metagame_card",
        "spellbook_box_ev_rankings",
        "spellbook_box_ev_history",
        "spellbook_box_price_history",
        "spellbook_box_breakeven",
        "spellbook_ebay_publish",
        "spellbook_ebay_lot_publish",
        "spellbook_ebay_reprice",
        "spellbook_ebay_price_limits_get",
        "spellbook_ebay_price_limit_enrollment_prepare",
        "spellbook_ebay_price_limit_enrollment_get",
        "spellbook_ebay_price_limit_enrollment_pages",
        "spellbook_ebay_price_limit_enrollment_continue",
        "spellbook_ebay_pricing_restoration_prepare",
        "spellbook_ebay_pricing_approval_prepare",
        "spellbook_ebay_pricing_approval_get",
        "spellbook_ebay_pricing_approval_execute",
        "spellbook_agent_pricing_protection",
        "spellbook_ebay_unpublish",
        "spellbook_ebay_job_status",
        "spellbook_manapool_sync_preview",
        "spellbook_manapool_sync_apply",
        "spellbook_marketplace_listings_adopt_preview",
        "spellbook_marketplace_listings_adopt_apply",
        "spellbook_sealed_listing_preview",
        "spellbook_sealed_listing_submit",
        "spellbook_sealed_listing_pause",
        "spellbook_tcg_listing_preview",
        "spellbook_tcg_listing_export",
        "spellbook_pokemon_tcg_staged_preview",
        "spellbook_ebay_connect_link",
        "spellbook_ebay_connection_status",
        "spellbook_ebay_shipping_policy_get",
        "spellbook_ebay_shipping_policy_set",
        "spellbook_ebay_shipping_mode_get",
        "spellbook_ebay_shipping_mode_set",
        "spellbook_ebay_combined_shipping_get",
        "spellbook_ebay_combined_shipping_set",
        "spellbook_ebay_order_discount_get",
        "spellbook_ebay_order_discount_set",
        "spellbook_ebay_order_discount_disable",
        "spellbook_manapool_connect_link",
        "spellbook_manapool_connection_status",
        "spellbook_marketplace_onboarding",
        "spellbook_item_photo_upload_link",
        "spellbook_pull_work",
        "spellbook_japanese_sourcing",
        "spellbook_riftbound_japanese_comparables",
        "spellbook_japan_source_scan",
        "spellbook_pricing_decision_explain",
        "spellbook_sku_price_controls",
        "spellbook_sku_minimum_floor_set",
        "spellbook_sku_minimum_floor_clear",
        "spellbook_sku_exact_price_lock_set",
        "spellbook_sku_exact_price_lock_clear",
        "spellbook_pricing_profiles_list",
        "spellbook_pricing_profile_get",
        "spellbook_pricing_profile_create",
        "spellbook_pricing_profile_update",
        "spellbook_pricing_profile_activate",
        "spellbook_pricing_amendments_list",
        "spellbook_pricing_amendment_get",
        "spellbook_pricing_amendment_create",
        "spellbook_pricing_amendment_update",
        "spellbook_pricing_amendment_delete",
        "spellbook_pricing_amendment_preview",
        "spellbook_pricing_amendment_preview_status",
        "spellbook_ebay_automation_set",
        "spellbook_manapool_automation_set",
        "spellbook_channel_lane_set",
        "spellbook_channel_pricing_profiles",
        "spellbook_channel_pricing_profile_set",
        "spellbook_tcg_extension_pairing",
        "spellbook_workspace_create",
        "spellbook_workspace_plan_status",
        "spellbook_free_seller_workspace_claim",
        "spellbook_seller_plan_checkout_link",
        "spellbook_return_address",
        "spellbook_return_address_save",
        "spellbook_alerts_list",
        "spellbook_alert_create",
        "spellbook_alert_delete",
        "spellbook_card_buylist_history",
        "spellbook_buylist_compare",
        "spellbook_order_proof_photos",
        "spellbook_repeat_buyers",
        "spellbook_collection_receipt",
        "spellbook_inventory_management_get",
        "spellbook_inventory_management_set",
        "spellbook_returned_package_work",
        "spellbook_returned_package_reship_print",
        "spellbook_returned_package_reship_dispatch",
        "login",
        "refresh"
      ],
      "type": "string",
      "description": "Which SpellBook operation failed. Required, one of the closed operation names."
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "maxLength": 30,
      "description": "ISO-8601 timestamp of when the failure occurred. Required."
    },
    "submissionId": {
      "type": "string",
      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$",
      "description": "A fresh ULID for this report. Reuse the exact same value and request body to retry within 24 hours; a new value starts a new report."
    },
    "clientVersion": {
      "type": "string",
      "pattern": "^\\d{1,4}\\.\\d{1,4}\\.\\d{1,4}$",
      "description": "This client's semantic version, e.g. \"1.2.3\". Required."
    },
    "correlationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      "description": "A correlation id from a prior response, if one was returned. Omit when none was given."
    }
  },
  "additionalProperties": false
}

spellbook_tcg_extension_pairing

Read whether this workspace has a paired TCGplayer browser extension, and get the SpellBook page where the seller pairs one. TCGplayer has no seller API, so SpellBook syncs TCGplayer listings and orders through a Chrome extension on the seller's own computer. Returns whether the account has extension access, the current session's status, when it was paired, when the extension last checked in, and its order sync state. If session is null or lastSeenAt is null, give the seller pairingPage.guideUrl to install the extension, then pairingPage.url to pair it. Call this tool again after they finish.

read-only

Argument	Type	Description
workspaceId*	string	The workspace to read extension pairing for, from spellbook_workspaces_list. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to read extension pairing for, from spellbook_workspaces_list. Required."
    }
  },
  "additionalProperties": false
}

spellbook_tcg_listing_export

Produce the CSV a person uploads to the TCGplayer portal, and mark those copies as listed in SpellBook. Call it only after spellbook_tcg_listing_preview and only once the person has said they will upload the file. Hand them the CSV and tell them plainly that SpellBook now believes these copies are listed, so the upload has to happen.

destructive

Argument	Type	Description
floorPrice	number	Must match the value shown in spellbook_tcg_listing_preview to export the same priced candidates.
sampleSize	integer	Must match the value shown in spellbook_tcg_listing_preview to export the same candidate set.
workspaceId*	string	The workspace to export a TCGplayer upload CSV for. Required; writes listing records for this workspace.
marketMultiplier	number	Must match the value shown in spellbook_tcg_listing_preview to export the same priced candidates.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "floorPrice": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0,
      "description": "Must match the value shown in spellbook_tcg_listing_preview to export the same priced candidates."
    },
    "sampleSize": {
      "type": "integer",
      "maximum": 5000,
      "minimum": 1,
      "description": "Must match the value shown in spellbook_tcg_listing_preview to export the same candidate set."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to export a TCGplayer upload CSV for. Required; writes listing records for this workspace."
    },
    "marketMultiplier": {
      "type": "number",
      "maximum": 10,
      "description": "Must match the value shown in spellbook_tcg_listing_preview to export the same priced candidates.",
      "exclusiveMinimum": 0
    }
  },
  "additionalProperties": false
}

spellbook_tcg_listing_preview

Show which cards in one workspace would be listed on TCGplayer, and at what price, without changing anything. TCGplayer has no server-side publish, so the real path is a CSV a person uploads to the TCGplayer portal. Call this first and show the person the candidates and the totals, then call spellbook_tcg_listing_export only once they have agreed to upload the file.

read-only

Argument	Type	Description
cursor	string	Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page.
floorPrice	number	A price floor in USD for this preview. Omit to use the workspace's stored floor.
sampleSize	integer	Maximum candidate rows to preview. Omit for the default sample size.
workspaceId*	string	The workspace to preview a TCGplayer listing run for. Required.
marketMultiplier	number	Price multiplier applied to market price for this preview. Omit to use the workspace's stored pricing.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "floorPrice": {
      "type": "number",
      "maximum": 1000,
      "minimum": 0,
      "description": "A price floor in USD for this preview. Omit to use the workspace's stored floor."
    },
    "sampleSize": {
      "type": "integer",
      "maximum": 5000,
      "minimum": 1,
      "description": "Maximum candidate rows to preview. Omit for the default sample size."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to preview a TCGplayer listing run for. Required."
    },
    "marketMultiplier": {
      "type": "number",
      "maximum": 10,
      "description": "Price multiplier applied to market price for this preview. Omit to use the workspace's stored pricing.",
      "exclusiveMinimum": 0
    }
  },
  "additionalProperties": false
}

spellbook_workspace_create

Create the signed-in seller's first workspace when spellbook_workspaces_list comes back empty. It makes a workspace the seller owns. A signup Store trial starts only when its flag is on and free Seller access is not configured for this workspace. When the seller already has a workspace, it returns the first one and creates nothing, so a repeated call is safe. It returns workspaceId, name, role, and created.

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

spellbook_workspace_plan_status

Read one workspace's Store plan and Seller usage status: tier, stored plan status, trialExpiresAt, sellerToolsUnlocked, and freeSellerCap's scope, observedAt, sellerSource, limitKind, nominalUnitAllowance, managedListedUnitCount, selectedListingKeyCount, count exactness, usageLimitations, and compatibility fields. selectedListingKeyCount counts explicit selected TCGplayer and ManaPool policy memberships; it is not a total of current marketplace keys. Legacy all-mode, eBay, and CardTrader key totals are not enumerated. The 10,000-unit figure is a soft reference. A free owner must explicitly choose one workspace with spellbook_free_seller_workspace_claim before free Seller access begins. Read this status again after the claim.

read-only

Argument	Type	Description
workspaceId*	string	The workspace to read the plan for. The caller must be a member. Required.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to read the plan for. The caller must be a member. Required."
    }
  },
  "additionalProperties": false
}

spellbook_workspaces_list

List the authenticated customer's existing workspaces with workspaceId, name, membership role and status. Owner, admin and member roles are preserved. Discover a workspace before selecting it; this read creates no workspace or trial. When the list is empty, spellbook_workspace_create makes the first one.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {},
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "alertType"
  ],
  "properties": {
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The finish to watch, matching the finish codes spellbook_printings_search returns. Required for a buylist_watch with scope card."
    },
    "isFoil": {
      "type": "boolean",
      "description": "Whether the watched card is foil. Required for every non-buylist_watch type."
    },
    "assetKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The printing id for a card or the product id for a box. Required for every non-buylist_watch type."
    },
    "alertType": {
      "enum": [
        "price",
        "metagame",
        "supply_signal",
        "eu_spread",
        "buylist_spread",
        "buylist_vs_cost_basis",
        "spread_compression",
        "fair_value_divergence",
        "sealed_breakeven_positive",
        "restock",
        "buylist_watch"
      ],
      "type": "string",
      "description": "The kind of alert. buylist_watch watches dealer buy offers against inventory or one printing. Required."
    },
    "assetName": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A display name for the watched asset. Required for every non-buylist_watch type. Optional for buylist_watch."
    },
    "assetType": {
      "enum": [
        "card",
        "box"
      ],
      "type": "string",
      "description": "Whether the alert watches a card or a sealed box. Required for every non-buylist_watch type."
    },
    "direction": {
      "enum": [
        "above",
        "below"
      ],
      "type": "string",
      "description": "Whether the alert fires when the price is above or below threshold. Required for crossed and for every non-buylist_watch type."
    },
    "threshold": {
      "type": "number",
      "description": "The USD price the alert compares against. Required for crossed and for every non-buylist_watch type.",
      "exclusiveMinimum": 0
    },
    "scryfallId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The exact printing id from spellbook_printings_search. Required for a buylist_watch with scope card and for a card alert."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the alert belongs to, from spellbook_workspaces_list. Required."
    },
    "buylistVendor": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "For buylist_watch: the dealer to watch, as SpellBook stores the vendor name. Omit to watch Card Kingdom."
    },
    "buylistWatchScope": {
      "enum": [
        "inventory",
        "card"
      ],
      "type": "string",
      "description": "For buylist_watch: inventory watches every sellable item in the workspace, card watches one printing and finish. Required for buylist_watch."
    },
    "buylistWatchCondition": {
      "enum": [
        "buying_again",
        "crossed"
      ],
      "type": "string",
      "description": "For buylist_watch: buying_again or crossed. crossed also needs direction and threshold. Required for buylist_watch."
    }
  },
  "additionalProperties": false
}

Argument	Type	Description
q	string	Product-name token filter, not a numeric product-id lookup. Broad collector searches may also match Collector's Edition Commander decks; use box_type and verify the returned boxId. Omit to include every product.
game	string	Restrict rankings to one game. Omit for the mixed supported-game ranking. A registered game without production EV returns an empty ranking plus sealedIntelligence.reason and missingFields.
sort	string	Which computed field ranks the rows. Defaults to evRatio, the stored totalEV ratio using acquirableFloorUsd when its basis is known; use spreadUsd for totalEV minus marketPrice. n0Full, n0LandAdjusted and n0Sellable rank by packs needed under that valuation basis. A null sort value, a preorder row and an unverified row come after the other rows in either direction.
limit	integer	Maximum rows to return, 1 to 150. Omit for the default of 50.
cursor	string	Opaque nextCursor from a previous page, passed back unchanged. Omit to start from the first page.
box_type	string	Exact box-type value from a ranking row, such as collector for Collector Boosters or commander for Commander decks. Omit to include every box type.
sort_dir	string	Sort direction for `sort`. Defaults to desc, highest first. Pass asc with an n0 sort to list the fewest packs first.
max_price	number	Maximum market price a row may have to be returned. Omit for no ceiling.
min_ev_ratio	number	Minimum stored evRatio a row must have to be returned. Rows with a null ratio are excluded. Omit for no floor.

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Product-name token filter, not a numeric product-id lookup. Broad collector searches may also match Collector's Edition Commander decks; use box_type and verify the returned boxId. Omit to include every product."
    },
    "game": {
      "enum": [
        "mtg",
        "riftbound",
        "pokemon"
      ],
      "type": "string",
      "description": "Restrict rankings to one game. Omit for the mixed supported-game ranking. A registered game without production EV returns an empty ranking plus sealedIntelligence.reason and missingFields."
    },
    "sort": {
      "enum": [
        "evRatio",
        "totalEV",
        "spreadUsd",
        "marketPrice",
        "packEV",
        "packEvRatio",
        "packPrice",
        "n0Full",
        "n0Sellable",
        "n0LandAdjusted"
      ],
      "type": "string",
      "default": "evRatio",
      "description": "Which computed field ranks the rows. Defaults to evRatio, the stored totalEV ratio using acquirableFloorUsd when its basis is known; use spreadUsd for totalEV minus marketPrice. n0Full, n0LandAdjusted and n0Sellable rank by packs needed under that valuation basis. A null sort value, a preorder row and an unverified row come after the other rows in either direction."
    },
    "limit": {
      "type": "integer",
      "default": 50,
      "maximum": 150,
      "minimum": 1,
      "description": "Maximum rows to return, 1 to 150. Omit for the default of 50."
    },
    "cursor": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "Opaque nextCursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "box_type": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact box-type value from a ranking row, such as collector for Collector Boosters or commander for Commander decks. Omit to include every box type."
    },
    "sort_dir": {
      "enum": [
        "asc",
        "desc"
      ],
      "type": "string",
      "default": "desc",
      "description": "Sort direction for `sort`. Defaults to desc, highest first. Pass asc with an n0 sort to list the fewest packs first."
    },
    "max_price": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum market price a row may have to be returned. Omit for no ceiling."
    },
    "min_ev_ratio": {
      "type": "number",
      "description": "Minimum stored evRatio a row must have to be returned. Rows with a null ratio are excluded. Omit for no floor."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "title",
    "summary",
    "cards",
    "priceUsd",
    "shippingUsd"
  ],
  "properties": {
    "cards": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "scryfallId",
          "quantity"
        ],
        "properties": {
          "quantity": {
            "type": "integer",
            "maximum": 60,
            "minimum": 1,
            "description": "How many copies of this card the deck holds."
          },
          "scryfallId": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The Scryfall id of one printing, from spellbook_printings_search. Any printing of the card counts toward the same card name."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "The deck list, at most 100 rows and 500 cards in total. Rows that share a card name are merged. Required."
    },
    "title": {
      "type": "string",
      "maxLength": 80,
      "minLength": 1,
      "description": "The eBay listing title, at most 80 characters. Required."
    },
    "dryRun": {
      "type": "boolean",
      "default": true,
      "description": "True previews the listing with no eBay call. False publishes for real. Defaults to true; a live run needs an explicit false."
    },
    "summary": {
      "type": "string",
      "maxLength": 1000,
      "minLength": 1,
      "description": "A short description of the deck for the listing body, at most 1000 characters. Required."
    },
    "priceUsd": {
      "type": "number",
      "maximum": 2000,
      "minimum": 0.99,
      "description": "The listing price in USD for the whole deck, from 0.99 to 2000. Required. The person decides it."
    },
    "archetype": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "An archetype label for the listing, such as Burn. Omit when the deck has none."
    },
    "deckFormat": {
      "type": "string",
      "maxLength": 40,
      "minLength": 1,
      "description": "A Scryfall legality format key such as pauper or commander. When set, a card that is not legal or restricted in it blocks a live run. Omit to skip the legality check."
    },
    "shippingUsd": {
      "type": "number",
      "maximum": 50,
      "minimum": 0,
      "description": "The flat shipping charge in USD the buyer pays, from 0 to 50. Use 0 for free shipping. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose copies make up the deck. Required."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "scope",
    "startsAt",
    "endsAt",
    "decreaseCents",
    "increaseCents",
    "expectedPolicyRevision"
  ],
  "properties": {
    "scope": {
      "type": "string",
      "const": "known_ordinary_usd_live",
      "description": "Known ordinary live USD listings for the verified eBay account. Required."
    },
    "endsAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "Owner-selected exclusive admission-window end as a UTC timestamp. Required."
    },
    "startsAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "Owner-selected inclusive admission-window start as a UTC timestamp. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "decreaseCents": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Owner-selected absolute USD cents below each observed baseline. Required; no default."
    },
    "increaseCents": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Owner-selected absolute USD cents above each observed baseline. Required; no default."
    },
    "expectedPolicyRevision": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Policy revision from spellbook_ebay_price_limits_get. Required."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "multiplier"
  ],
  "properties": {
    "binId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Restrict publishing to one exact bin. Omit to consider every owned copy."
    },
    "dryRun": {
      "type": "boolean",
      "default": true,
      "description": "True previews the run with no live listings created. False publishes for real. Defaults to true; a live run needs an explicit false."
    },
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Restrict publishing to these exact Item ids, from a prior spellbook_inventory_items_query. Pass one id to list one card. The owned-only rule still applies to each id. Omit to consider every owned copy."
    },
    "floorUsd": {
      "type": "number",
      "maximum": 100000,
      "minimum": 0,
      "description": "A price floor in USD that only ever raises a computed price. Omit for no floor."
    },
    "setCodes": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 20,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Restrict publishing to these set codes. Omit to consider every set."
    },
    "batchSize": {
      "type": "integer",
      "maximum": 2000,
      "minimum": 1,
      "description": "Maximum copies to submit in this call. Omit for the default batch size."
    },
    "multiplier": {
      "type": "number",
      "maximum": 20,
      "description": "Price multiplier applied to each copy's market price, e.g. 0.96 lists at 96% of market. Required.",
      "exclusiveMinimum": 0
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose owned copies to publish. Required."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId"
  ],
  "properties": {
    "binId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Restrict the run to one exact inventory bin. Omit for every live eBay listing in the workspace."
    },
    "dryRun": {
      "type": "boolean",
      "default": true,
      "description": "True previews the listings and counts with no marketplace change. False queues the reprice job. Defaults to true; applying requires explicit false."
    },
    "itemIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 100,
      "minItems": 1,
      "description": "Restrict the run to these exact listed Item ids from spellbook_inventory_items_query. Omit for every live eBay listing in the workspace."
    },
    "pricing": {
      "enum": [
        "multiplier",
        "saved_rules"
      ],
      "type": "string",
      "default": "multiplier",
      "description": "Use saved_rules to run the owner's accepted eBay strategy without caller pricing overrides. multiplier applies a one-run override where delegated permissions allow it."
    },
    "floorUsd": {
      "type": "number",
      "maximum": 100000,
      "minimum": 0,
      "description": "Optional minimum ask in USD. Existing backend floors and locks can still raise the resulting ask."
    },
    "setCodes": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 20,
        "minLength": 1
      },
      "maxItems": 50,
      "description": "Restrict the run to these set codes. Omit for every live eBay listing in the workspace."
    },
    "multiplier": {
      "type": "number",
      "maximum": 20,
      "description": "Market multiplier such as 0.96. Required with pricing multiplier; omit with saved_rules.",
      "exclusiveMinimum": 0
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace whose existing eBay listings to reprice. Required."
    },
    "acquisitionSource": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Restrict the run to one exact acquisition source. Omit for every live eBay listing in the workspace."
    },
    "skipIfWithinPercent": {
      "type": "number",
      "default": 2,
      "maximum": 50,
      "minimum": 0,
      "description": "Skip an existing ask already within this percentage of the target. Defaults to 2."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "source",
    "csv"
  ],
  "properties": {
    "csv": {
      "type": "string",
      "maxLength": 200000,
      "minLength": 1,
      "description": "The full CSV text, header row included, exactly as the export produced it. Required. At most 200,000 characters."
    },
    "source": {
      "enum": [
        "manabox",
        "tcg"
      ],
      "type": "string",
      "description": "Which export this is: manabox for a ManaBox CSV (needs Scryfall ID, Quantity, Condition and Foil columns), tcg for a TCGplayer seller inventory export (needs the TCGplayer Id column). Required."
    },
    "binName": {
      "type": "string",
      "pattern": "^[A-Za-z0-9 _-]+$",
      "maxLength": 48,
      "minLength": 1,
      "description": "A human name for that one bin, 1 to 48 letters, digits, spaces, dashes or underscores. Honored only when oneBinPerUpload is true. A name another import already holds is refused."
    },
    "binPrefix": {
      "type": "string",
      "pattern": "^[A-Z]$",
      "description": "One capital letter that starts fallback bin codes for copies without a mapped location, e.g. C gives C0001, C0002. Defaults to C."
    },
    "totalCost": {
      "type": "number",
      "maximum": 10000000,
      "minimum": 0,
      "description": "What the seller paid for the whole file in USD, split equally across every copy. Omit when the seller has not stated it; omitting records zero cost."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to import into. Required; writes only to this workspace."
    },
    "blankLocation": {
      "enum": [
        "generate",
        "error"
      ],
      "type": "string",
      "description": "For a blank cell in a selected location column: generate assigns a fallback bin; error refuses the whole import before writing copies. Defaults to generate. Has no effect without a selected column."
    },
    "locationColumn": {
      "anyOf": [
        {
          "enum": [
            "auto",
            "none"
          ],
          "type": "string"
        },
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0
        }
      ],
      "description": "Location column: auto detects a single common location or bin header, none ignores source locations, or a zero-based original CSV column index selects it explicitly. Defaults to auto. Multiple matching headers require an explicit choice."
    },
    "oneBinPerUpload": {
      "type": "boolean",
      "description": "True puts the whole file in one fresh bin instead of packing 200 cards per bin across the rolling sequence. Defaults to false. Refused when any imported row has a mapped location."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "tcgProductId",
    "paidPriceUsd",
    "acquisitionDate",
    "binPrefix"
  ],
  "properties": {
    "binPrefix": {
      "type": "string",
      "pattern": "^[A-Z]$",
      "description": "One capital letter that starts the auto-assigned bin codes, e.g. C gives C0001. Required."
    },
    "copyCount": {
      "type": "integer",
      "maximum": 20,
      "minimum": 1,
      "description": "How many identical decks were opened, 1 to 20. Defaults to 1."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace to add the cards to, from spellbook_workspaces_list. Required; writes only to this workspace."
    },
    "paidPriceUsd": {
      "type": "number",
      "maximum": 100000,
      "minimum": 0,
      "description": "What the seller paid for ONE deck in USD. Required. Send 0 only when the deck cost nothing. Every copy of the deck is recorded at this price."
    },
    "tcgProductId": {
      "type": "integer",
      "maximum": 9007199254740991,
      "description": "Exact TCGplayer product id of the sealed precon deck, from spellbook_sealed_product_search. Required. A product that is not a single Commander or Riftbound precon deck is refused.",
      "exclusiveMinimum": 0
    },
    "oneBinPerDeck": {
      "type": "boolean",
      "description": "True puts each deck in its own fresh bin. Defaults to false, which packs the cards into the rolling bin sequence."
    },
    "acquisitionDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "The date the seller bought the deck, as YYYY-MM-DD. Required."
    },
    "overrideDuplicate": {
      "type": "boolean",
      "description": "True imports the deck even when this seller already imported the same product. Set it only when the person confirms a second physical deck."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum rows to return, from 1 to 100. Defaults to 25."
    },
    "finish": {
      "enum": [
        "nf",
        "fo",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "Optional exact finish filter."
    },
    "cohortId": {
      "enum": [
        "pokemon",
        "pokemon-en",
        "pokemon-ja"
      ],
      "type": "string",
      "description": "Optional Pokemon cohort. Use pokemon-ja or pokemon-en to keep language evidence isolated."
    },
    "language": {
      "enum": [
        "en",
        "ja"
      ],
      "type": "string",
      "description": "Optional exact language filter."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "Optional condition filter."
    },
    "productId": {
      "type": "string",
      "pattern": "^pokemon:tcgp:[1-9]\\d*$",
      "description": "Optional exact Pokemon catalog product id from spellbook_printings_search."
    },
    "proxyFeeUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional proxy fee assumption in USD; omitted keeps landed cost incomplete."
    },
    "importDutyRate": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional import duty rate as a decimal; omitted keeps landed cost incomplete."
    },
    "sellingFeeRate": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional selling fee rate as a decimal; omitted keeps net proceeds incomplete."
    },
    "otherSellingUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional other selling cost in USD; omitted keeps net proceeds incomplete."
    },
    "importChargesUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional import charges assumption in USD; omitted keeps landed cost incomplete."
    },
    "inboundShippingUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional inbound shipping assumption in USD; omitted keeps landed cost incomplete."
    },
    "sellingFixedFeeUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional selling fixed fee in USD; omitted keeps net proceeds incomplete."
    },
    "otherAcquisitionUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional other acquisition cost in USD; omitted keeps landed cost incomplete."
    },
    "outboundShippingUsd": {
      "anyOf": [
        {
          "type": "number",
          "maximum": 1000000,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional outbound shipping assumption in USD; omitted keeps net proceeds incomplete."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "name",
    "priority",
    "selector",
    "marketplaceScope",
    "mode"
  ],
  "properties": {
    "mode": {
      "type": "object",
      "required": [
        "multiplier"
      ],
      "properties": {
        "multiplier": {
          "type": "number",
          "description": "Absolute multiplier applied by this amendment. Required.",
          "exclusiveMinimum": 0
        },
        "protectedBand": {
          "type": "object",
          "required": [
            "thresholdUsd",
            "multiplier"
          ],
          "properties": {
            "multiplier": {
              "type": "number",
              "description": "Protected multiplier at or above the threshold.",
              "exclusiveMinimum": 0
            },
            "thresholdUsd": {
              "type": "number",
              "description": "Original market anchor threshold in USD.",
              "exclusiveMinimum": 0
            }
          },
          "description": "Optional seller-approved protected band.",
          "additionalProperties": false
        }
      },
      "description": "Absolute multiplier and optional protected band. Required.",
      "additionalProperties": false
    },
    "name": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Seller-selected amendment name. Required."
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ],
      "description": "Optional seller notes; null clears notes."
    },
    "enabled": {
      "type": "boolean",
      "default": true,
      "description": "Whether the amendment starts enabled. Omit for enabled."
    },
    "priority": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "Seller-selected precedence priority. Required."
    },
    "selector": {
      "type": "object",
      "properties": {
        "finish": {
          "enum": [
            "nf",
            "fo",
            "etched",
            "surge",
            "rh",
            "1e",
            "1e-fo"
          ],
          "type": "string",
          "description": "Optional finish selector."
        },
        "setCode": {
          "type": "string",
          "maxLength": 32,
          "minLength": 1,
          "description": "Set code selector."
        },
        "condition": {
          "enum": [
            "NM",
            "LP",
            "MP",
            "HP",
            "DMG"
          ],
          "type": "string",
          "description": "Optional condition selector."
        },
        "scryfallId": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1,
          "description": "Exact Scryfall printing selector. Requires setCode when supplied."
        },
        "releaseFamilyCode": {
          "type": "string",
          "maxLength": 32,
          "minLength": 1,
          "description": "Release family selector."
        },
        "originalAnchorPriceBand": {
          "type": "object",
          "properties": {
            "maxUsd": {
              "type": "number",
              "minimum": 0,
              "description": "Protected band upper bound in USD."
            },
            "minUsd": {
              "type": "number",
              "minimum": 0,
              "description": "Protected band lower bound in USD."
            }
          },
          "description": "Optional original market anchor band selector.",
          "additionalProperties": false
        }
      },
      "description": "The bounded inventory selector. Required.",
      "additionalProperties": false
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "marketplaceScope": {
      "anyOf": [
        {
          "type": "string",
          "const": "all",
          "description": "Apply across all supported marketplaces."
        },
        {
          "type": "object",
          "required": [
            "channels"
          ],
          "properties": {
            "channels": {
              "type": "array",
              "items": {
                "enum": [
                  "ebay",
                  "tcg",
                  "manapool",
                  "shopify",
                  "cardtrader"
                ],
                "type": "string"
              },
              "maxItems": 5,
              "minItems": 1,
              "description": "Specific marketplace channels for this amendment."
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Marketplace scope. Required."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "amendmentId"
  ],
  "properties": {
    "mode": {
      "type": "object",
      "required": [
        "multiplier"
      ],
      "properties": {
        "multiplier": {
          "type": "number",
          "description": "Absolute multiplier applied by this amendment. Required.",
          "exclusiveMinimum": 0
        },
        "protectedBand": {
          "type": "object",
          "required": [
            "thresholdUsd",
            "multiplier"
          ],
          "properties": {
            "multiplier": {
              "type": "number",
              "description": "Protected multiplier at or above the threshold.",
              "exclusiveMinimum": 0
            },
            "thresholdUsd": {
              "type": "number",
              "description": "Original market anchor threshold in USD.",
              "exclusiveMinimum": 0
            }
          },
          "description": "Optional seller-approved protected band.",
          "additionalProperties": false
        }
      },
      "description": "Replacement absolute multiplier and optional protected band.",
      "additionalProperties": false
    },
    "name": {
      "type": "string",
      "maxLength": 120,
      "minLength": 1,
      "description": "Replacement seller-selected name."
    },
    "notes": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000
        },
        {
          "type": "null"
        }
      ],
      "description": "Replacement notes; null clears notes."
    },
    "enabled": {
      "type": "boolean",
      "description": "Replacement enabled state."
    },
    "priority": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": -9007199254740991,
      "description": "Replacement precedence priority."
    },
    "selector": {
      "type": "object",
      "properties": {
        "finish": {
          "enum": [
            "nf",
            "fo",
            "etched",
            "surge",
            "rh",
            "1e",
            "1e-fo"
          ],
          "type": "string",
          "description": "Optional finish selector."
        },
        "setCode": {
          "type": "string",
          "maxLength": 32,
          "minLength": 1,
          "description": "Set code selector."
        },
        "condition": {
          "enum": [
            "NM",
            "LP",
            "MP",
            "HP",
            "DMG"
          ],
          "type": "string",
          "description": "Optional condition selector."
        },
        "scryfallId": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1,
          "description": "Exact Scryfall printing selector. Requires setCode when supplied."
        },
        "releaseFamilyCode": {
          "type": "string",
          "maxLength": 32,
          "minLength": 1,
          "description": "Release family selector."
        },
        "originalAnchorPriceBand": {
          "type": "object",
          "properties": {
            "maxUsd": {
              "type": "number",
              "minimum": 0,
              "description": "Protected band upper bound in USD."
            },
            "minUsd": {
              "type": "number",
              "minimum": 0,
              "description": "Protected band lower bound in USD."
            }
          },
          "description": "Optional original market anchor band selector.",
          "additionalProperties": false
        }
      },
      "description": "Replacement bounded selector.",
      "additionalProperties": false
    },
    "amendmentId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The exact saved amendment id from a prior amendment read. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace the seller selected. The caller must own it. Required."
    },
    "marketplaceScope": {
      "anyOf": [
        {
          "type": "string",
          "const": "all",
          "description": "Apply across all supported marketplaces."
        },
        {
          "type": "object",
          "required": [
            "channels"
          ],
          "properties": {
            "channels": {
              "type": "array",
              "items": {
                "enum": [
                  "ebay",
                  "tcg",
                  "manapool",
                  "shopify",
                  "cardtrader"
                ],
                "type": "string"
              },
              "maxItems": 5,
              "minItems": 1,
              "description": "Specific marketplace channels for this amendment."
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Replacement marketplace scope."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "orderRef",
    "marketplace",
    "rows"
  ],
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "scryfallId",
          "cardName",
          "setCode",
          "collectorNumber",
          "condition",
          "finish",
          "quantity",
          "unitPriceUsd"
        ],
        "properties": {
          "finish": {
            "enum": [
              "nf",
              "fo",
              "etched",
              "surge",
              "rh",
              "1e",
              "1e-fo"
            ],
            "type": "string",
            "description": "The finish of these copies, using the values listed in this field. Required."
          },
          "setCode": {
            "type": "string",
            "maxLength": 20,
            "minLength": 1,
            "description": "The set code of this exact printing. Required."
          },
          "cardName": {
            "type": "string",
            "maxLength": 200,
            "minLength": 1,
            "description": "The card's name. Required."
          },
          "quantity": {
            "type": "integer",
            "maximum": 500,
            "minimum": 1,
            "description": "How many copies of this printing, condition and finish the order bought. Required, at least 1."
          },
          "condition": {
            "enum": [
              "NM",
              "LP",
              "MP",
              "HP",
              "DMG"
            ],
            "type": "string",
            "description": "The condition the listing was sold as. Required."
          },
          "scryfallId": {
            "type": "string",
            "maxLength": 64,
            "minLength": 1,
            "description": "The exact printing id, from spellbook_printings_search. Required; a wrong id records the wrong card."
          },
          "unitPriceUsd": {
            "type": "number",
            "maximum": 1000000,
            "minimum": 0,
            "description": "The price paid for ONE copy in USD, as the checkout showed it. Required."
          },
          "collectorNumber": {
            "type": "string",
            "maxLength": 20,
            "minLength": 1,
            "description": "The collector number of this exact printing. Required."
          }
        },
        "additionalProperties": false
      },
      "maxItems": 200,
      "minItems": 1,
      "description": "The order's lines, one per exact printing, condition and finish. Required, at least one."
    },
    "orderRef": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The marketplace's order number from the checkout confirmation. Required. The same order number groups every copy for receiving."
    },
    "sellerName": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The seller's store name on the marketplace, when the checkout shows one. Shown beside the order in the incoming list."
    },
    "marketplace": {
      "enum": [
        "tcgplayer",
        "ebay",
        "manapool",
        "cardtrader",
        "other"
      ],
      "type": "string",
      "description": "Where the order was placed. Required. Use other for any marketplace not listed."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that bought the cards, from spellbook_workspaces_list. Required; writes only to this workspace."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "sessionIds",
    "returnReason",
    "idempotencyKey"
  ],
  "properties": {
    "sessionIds": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200,
        "minLength": 1
      },
      "maxItems": 50,
      "minItems": 1,
      "description": "Up to 50 sessionId values from spellbook_returned_package_lookup. For a shared multi-order sheet, send exactly one sessionId with its matching externalOrderId. Required, at least one."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that shipped the orders, from spellbook_workspaces_list. Required; writes only to this workspace."
    },
    "returnReason": {
      "enum": [
        "address_issue",
        "insufficient_postage",
        "unclaimed_or_refused",
        "damaged_in_transit",
        "unknown",
        "other"
      ],
      "type": "string",
      "description": "Why the carrier returned the packages, applied to every session in this call. address_issue means the address was wrong or incomplete, and the reship then requires a corrected address. unclaimed_or_refused covers an unclaimed or refused letter. Use unknown when the return label gives no reason. Required."
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A key you choose for this batch, such as rts- followed by the order id. Required. Send the same key on a retry after a timeout. A new key on a session that already has an open case returns already_open."
    },
    "externalOrderId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The marketplace order id of the one returned order, as the marketplace prints it. Send it only with exactly one sessionId, when that pull sheet holds several orders. Omit it otherwise."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "productId",
    "finish",
    "condition",
    "qty",
    "salePricePerUnit",
    "marketplace",
    "orderId"
  ],
  "properties": {
    "qty": {
      "type": "integer",
      "maximum": 500,
      "minimum": 1,
      "description": "How many copies sold. Required."
    },
    "note": {
      "type": "string",
      "maxLength": 500,
      "minLength": 1,
      "description": "A free-text note stored with the sale. Optional."
    },
    "binId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "Sell only copies from this bin. Omit to take the oldest copies from any bin."
    },
    "finish": {
      "enum": [
        "nf",
        "fo",
        "etched",
        "surge",
        "rh",
        "1e",
        "1e-fo"
      ],
      "type": "string",
      "description": "The finish of the sold copies, matching the finish recorded in inventory. Pokemon supports nf (Normal/Unlimited), fo (Holofoil), rh (Reverse Holofoil), 1e (1st Edition) and 1e-fo (1st Edition Holofoil). Required."
    },
    "orderId": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "A stable reference for this sale, such as the buyer's order number or a receipt number. Required. A second call with the same orderId for the same printing, finish and condition returns the first sale with replayed true and sells nothing."
    },
    "buyerName": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "The buyer's name as the customer stated it. Optional."
    },
    "condition": {
      "enum": [
        "NM",
        "LP",
        "MP",
        "HP",
        "DMG"
      ],
      "type": "string",
      "description": "The condition of the sold copies, matching how they were recorded. Required."
    },
    "productId": {
      "type": "string",
      "maxLength": 64,
      "minLength": 1,
      "description": "The exact printing id, from spellbook_printings_search or spellbook_inventory_holdings. Required; a wrong id sells the wrong card."
    },
    "occurredAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the sale happened, as an ISO-8601 timestamp. Omit to use the time of this call."
    },
    "marketplace": {
      "enum": [
        "tcg",
        "manapool",
        "ebay",
        "in_person",
        "buylist",
        "unknown"
      ],
      "type": "string",
      "description": "Where the sale happened. in_person covers a store buy or a trade. buylist covers a sale to a dealer's buylist and needs buylistVendor. Required."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that held the sold copies, from spellbook_workspaces_list. Required."
    },
    "buylistVendor": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The dealer that bought the copies, such as Card Kingdom. Required when marketplace is buylist. Omit for every other marketplace."
    },
    "salePricePerUnit": {
      "type": "number",
      "minimum": 0,
      "description": "Price received PER COPY in USD, before any fee. Not the order total. Required."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "mode": {
      "enum": [
        "nonfoil",
        "foil",
        "both"
      ],
      "type": "string",
      "default": "nonfoil",
      "description": "Price mode. nonfoil uses regular prices for the price floor and ceiling; foil uses foil prices; both requires positive regular and foil inputs and uses the regular price bounds. Band and change30d_max/change90d_min/move_ratio_min fields remain regular-price statistics in every mode."
    },
    "page": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 1,
      "description": "Page number, from 1. Read totalPages on the response before paging. Omit for the first page."
    },
    "sort": {
      "enum": [
        "changePct",
        "price",
        "name",
        "swing30d",
        "foilPrice",
        "foilChangePct",
        "premium"
      ],
      "type": "string",
      "default": "changePct",
      "description": "Which field orders the rows. premium sorts foilPrice/price, a multiple, with missing or nonpositive inputs last. Use mode=both for that comparison. price and changePct always read regular prices; foilPrice and foilChangePct read foil prices. Both change sorts use period. swing30d reads the typical regular-price move and ignores period. Missing change or swing values come last. Defaults to changePct."
    },
    "period": {
      "enum": [
        "7d",
        "30d",
        "90d"
      ],
      "type": "string",
      "default": "90d",
      "description": "Which change window the changePct or foilChangePct sort reads. Defaults to 90d. Band fields always use the last 20 daily closes."
    },
    "sort_dir": {
      "enum": [
        "asc",
        "desc"
      ],
      "type": "string",
      "default": "desc",
      "description": "Sort direction for `sort`. Defaults to desc, largest first. Pass asc with changePct to list the biggest falls first."
    },
    "max_price": {
      "type": "number",
      "description": "Highest current price in USD. Omit for no ceiling.",
      "exclusiveMinimum": 0
    },
    "min_price": {
      "type": "number",
      "description": "Lowest current price in USD. Omit for the default, which is 1, or 5 once any band or z-score bound is set, because cheap printings sit flat for weeks.",
      "exclusiveMinimum": 0
    },
    "page_size": {
      "type": "integer",
      "default": 25,
      "maximum": 50,
      "minimum": 1,
      "description": "Rows per page, 1 to 50. Defaults to 25."
    },
    "zscore_max": {
      "type": "number",
      "description": "Highest z20 a row may have. A negative value such as -1.5 keeps cards priced below their 20 day mean. Omit for no ceiling."
    },
    "zscore_min": {
      "type": "number",
      "description": "Lowest z20 a row may have. Omit for no floor."
    },
    "band_pos_max": {
      "type": "number",
      "description": "Highest bbPos a row may have. 100 is the upper band. Pass a low value such as 10 to keep cards near the bottom of their range. Omit for no ceiling."
    },
    "band_pos_min": {
      "type": "number",
      "description": "Lowest bbPos a row may have. 0 is the lower band. Once any band or z-score bound is set, rows with a null bbPos are dropped. Omit for no floor."
    },
    "change30d_max": {
      "type": "number",
      "description": "Highest 30 day change a row may have, in percent. Pass a negative number to keep cards that fell. Rows with no 30 day change are dropped. Omit for no ceiling."
    },
    "change90d_min": {
      "type": "number",
      "description": "Lowest 90 day change a row may have, in percent. Pair a positive value with change30d_max to keep cards that fell this month inside a 90 day rise. Rows with no 90 day change are dropped. Omit for no floor."
    },
    "flat_days_min": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Fewest days since the price last changed. Use it for flat prices, which carry no band position. Omit for no floor."
    },
    "band_width_max": {
      "type": "number",
      "minimum": 0,
      "description": "Widest bbWidth a row may have, in percent of ma20. A small value keeps cards whose price barely moved. Omit for no ceiling."
    },
    "move_ratio_min": {
      "type": "number",
      "minimum": 0,
      "description": "Lowest ratio of the absolute change30d to swing30d a row may have. Pass 4 to keep cards whose 30 day move is at least 4 times their typical 30 day move, up or down. Rows with no swing30d, a zero swing30d, or a price under $1 thirty days back are dropped. Omit for no floor."
    },
    "squeeze_recent": {
      "type": "boolean",
      "description": "Pass true to keep only rows whose Bollinger band sat inside the Keltner channel on any of the last 5 days. Omit to keep every row."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "boxId",
    "kind"
  ],
  "properties": {
    "cap": {
      "type": "integer",
      "maximum": 1000,
      "minimum": 0,
      "description": "The most units to offer at once. Omit to offer every eligible unit."
    },
    "game": {
      "enum": [
        "mtg",
        "riftbound",
        "pokemon"
      ],
      "type": "string",
      "default": "mtg",
      "description": "The game of the product. Defaults to mtg."
    },
    "kind": {
      "enum": [
        "box",
        "pack",
        "case"
      ],
      "type": "string",
      "description": "The sealed kind, the kind on the same spellbook_sealed_portfolio row. Required, because units are counted by kind and boxId together."
    },
    "boxId": {
      "type": "string",
      "pattern": "^\\d{1,12}$",
      "description": "The TCGplayer product id of the sealed product, the boxId on a spellbook_sealed_portfolio row. Required."
    },
    "channel": {
      "enum": [
        "manapool",
        "tcgplayer"
      ],
      "type": "string",
      "default": "manapool",
      "description": "Marketplace to preview. Defaults to manapool."
    },
    "floorUsd": {
      "type": "number",
      "maximum": 100000,
      "description": "undercut only. The lowest ask in USD the rule may choose. Omit to use catalog market times floorMarketFraction.",
      "exclusiveMinimum": 0
    },
    "language": {
      "type": "string",
      "default": "EN",
      "maxLength": 8,
      "minLength": 2,
      "description": "The product language code, such as EN or JA. Defaults to EN."
    },
    "takeover": {
      "type": "boolean",
      "default": false,
      "description": "True adopts a listing on the selected marketplace that SpellBook did not create. Defaults to false; pass true only after the person agrees."
    },
    "priceRule": {
      "enum": [
        "market",
        "undercut"
      ],
      "type": "string",
      "description": "market asks the catalog market price. undercut sets the ask so the item plus the seller's own shipping lands one cent under the cheapest TCGplayer item plus shipping from another seller, never below the floor. Omit for market."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that holds the sealed units, from spellbook_workspaces_list. Required."
    },
    "fixedPriceUsd": {
      "type": "number",
      "maximum": 100000,
      "description": "A fixed ask in USD for every unit. Omit to list at the product's current market price. Cannot be combined with priceRule.",
      "exclusiveMinimum": 0
    },
    "floorMarketFraction": {
      "type": "number",
      "maximum": 1,
      "description": "undercut only. The floor as a fraction of catalog market, used when floorUsd is omitted. Defaults to 0.9.",
      "exclusiveMinimum": 0
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": [
    "workspaceId",
    "boxId",
    "kind",
    "expectedStockRevision",
    "expectedAskUsd",
    "idempotencyKey"
  ],
  "properties": {
    "cap": {
      "type": "integer",
      "maximum": 1000,
      "minimum": 0,
      "description": "The most units to offer at once. Omit to offer every eligible unit."
    },
    "game": {
      "enum": [
        "mtg",
        "riftbound",
        "pokemon"
      ],
      "type": "string",
      "default": "mtg",
      "description": "The game of the product. Defaults to mtg."
    },
    "kind": {
      "enum": [
        "box",
        "pack",
        "case"
      ],
      "type": "string",
      "description": "The sealed kind, the kind on the same spellbook_sealed_portfolio row. Required, because units are counted by kind and boxId together."
    },
    "boxId": {
      "type": "string",
      "pattern": "^\\d{1,12}$",
      "description": "The TCGplayer product id of the sealed product, the boxId on a spellbook_sealed_portfolio row. Required."
    },
    "channel": {
      "enum": [
        "manapool",
        "tcgplayer"
      ],
      "type": "string",
      "default": "manapool",
      "description": "Marketplace to submit to. Must match the preview. Defaults to manapool."
    },
    "floorUsd": {
      "type": "number",
      "maximum": 100000,
      "description": "undercut only. The lowest ask in USD the rule may choose. Omit to use catalog market times floorMarketFraction.",
      "exclusiveMinimum": 0
    },
    "language": {
      "type": "string",
      "default": "EN",
      "maxLength": 8,
      "minLength": 2,
      "description": "The product language code, such as EN or JA. Defaults to EN."
    },
    "takeover": {
      "type": "boolean",
      "default": false,
      "description": "True adopts a listing on the selected marketplace that SpellBook did not create. Defaults to false; pass true only after the person agrees."
    },
    "priceRule": {
      "enum": [
        "market",
        "undercut"
      ],
      "type": "string",
      "description": "market asks the catalog market price. undercut sets the ask so the item plus the seller's own shipping lands one cent under the cheapest TCGplayer item plus shipping from another seller, never below the floor. Omit for market."
    },
    "workspaceId": {
      "type": "string",
      "maxLength": 100,
      "minLength": 1,
      "description": "The workspace that holds the sealed units, from spellbook_workspaces_list. Required."
    },
    "fixedPriceUsd": {
      "type": "number",
      "maximum": 100000,
      "description": "A fixed ask in USD for every unit. Omit to list at the product's current market price. Cannot be combined with priceRule.",
      "exclusiveMinimum": 0
    },
    "expectedAskUsd": {
      "type": "number",
      "maximum": 100000,
      "description": "proposed.askUsd from the preview. Required; a different value means the market ask changed and the call is refused.",
      "exclusiveMinimum": 0
    },
    "idempotencyKey": {
      "type": "string",
      "maxLength": 200,
      "minLength": 8,
      "description": "A unique request key for this publish attempt, such as a new UUID. If the result is uncertain, preview current state before deciding on another submit. Required."
    },
    "floorMarketFraction": {
      "type": "number",
      "maximum": 1,
      "description": "undercut only. The floor as a fraction of catalog market, used when floorUsd is omitted. Defaults to 0.9.",
      "exclusiveMinimum": 0
    },
    "expectedStockRevision": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "proposed.stockRevision from the preview. Required; a different value means stock moved and the call is refused."
    },
    "expectedIntentRevision": {
      "anyOf": [
        {
          "type": "integer",
          "maximum": 9007199254740991,
          "minimum": 0
        },
        {
          "type": "null"
        }
      ],
      "description": "intentRevision from the preview. Pass it unchanged, null included."
    }
  },
  "additionalProperties": false
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "sets": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact set code(s) to filter to. Omit to include every set."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "maximum": 200,
      "minimum": 1,
      "description": "Maximum rows to return, 1 to 200. Omit for the default of 20."
    },
    "cursor": {
      "type": "string",
      "pattern": "^v1\\.[A-Za-z0-9_-]+$",
      "maxLength": 2000,
      "description": "Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page."
    },
    "isFoil": {
      "type": "boolean",
      "description": "True restricts to foil rows, false to non-foil. Omit to include both."
    },
    "rarity": {
      "type": "string",
      "maxLength": 200,
      "minLength": 1,
      "description": "Exact rarity to filter to. Omit to include every rarity."
    },
    "sortBy": {
      "enum": [
        "totalPotentialProfitUsd",
        "spreadUsd",
        "spreadPct",
        "bestBuyPrice",
        "usPriceUsd",
        "actionableQuantity"
      ],
      "type": "string",
      "description": "Which field ranks the rows. Omit for the default order."
    },
    "sortDir": {
      "enum": [
        "asc",
        "desc"
      ],
      "type": "string",
      "description": "Sort direction for sortBy. Omit for the default direction."
    },
    "minCkQty": {
      "type": "integer",
      "maximum": 100000,
      "minimum": 0,
      "description": "Minimum Card Kingdom buylist quantity a row must have. Omit for no floor."
    },
    "minValue": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Minimum acquisition value in USD a row must have to be returned. Omit for no floor."
    },
    "minSpreadPct": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Minimum spread percentage a row must have to be returned. Omit for no floor."
    },
    "minSpreadUsd": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Minimum spread in USD a row must have to be returned. Omit for no floor."
    },
    "minTotalPotentialProfitUsd": {
      "type": "number",
      "maximum": 1000000,
      "minimum": 0,
      "description": "Minimum total potential profit in USD a row must have to be returned. Omit for no floor."
    }
  },
  "additionalProperties": false
}