Input schema (JSON)
{
"type": "object",
"oneOf": [
{
"not": {
"required": [
"items"
]
},
"title": "Single SKU",
"required": [
"sku"
]
},
{
"not": {
"required": [
"sku"
]
},
"title": "Basket",
"required": [
"items"
]
}
],
"required": [
"total_cost",
"max_total_sats",
"quote_id",
"accept_terms"
],
"properties": {
"sku": {
"type": "string",
"description": "Catalog id or slug for a single buy. Omit when items is set."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"sku"
],
"properties": {
"sku": {
"type": "string",
"description": "Catalog id or slug for this line."
},
"params": {
"anyOf": [
{
"type": "object"
},
{
"type": "array",
"items": {}
}
],
"description": "Fields from exampleCall or describe_sku for this line. An object, or a JSON array when that SKU body is an array."
},
"quantity": {
"type": "integer",
"maximum": 3,
"minimum": 1,
"description": "How many calls for this line. Default 1, maximum 3."
},
"confirm_duplicates": {
"type": "boolean",
"description": "Set true to allow this line to repeat."
}
}
},
"maxItems": 8,
"description": "Basket. One entry per SKU the user asked for. One total_cost and one approval for the whole list. A repeated line is refused unless confirm_duplicates is true on this call or on that line."
},
"query": {
"type": "string",
"description": "Free-text query when the SKU has no listed fields."
},
"params": {
"anyOf": [
{
"type": "object"
},
{
"type": "array",
"items": {}
}
],
"description": "Fields from exampleCall or describe_sku. An object of flat keys, requestBody / query / path, or a JSON array when the SKU body is an array."
},
"dry_run": {
"type": "boolean",
"description": "Set true to run every limit, approval, and balance check and return the resulting code. Nothing is charged, no approval is stored, and the hourly buy slot is not used. simulate_balance_sats and simulate_auto_approve_sats apply only when this is true."
},
"currency": {
"enum": [
"USD",
"EUR",
"GBP",
"CAD",
"AUD",
"JPY",
"CHF",
"BRL",
"MXN",
"INR"
],
"type": "string",
"description": "ISO 4217 code used in total_cost. Default USD. Use the user's local currency when you know it. Supported: USD, EUR, GBP, CAD, AUD, JPY, CHF, BRL, MXN, INR."
},
"quantity": {
"type": "integer",
"maximum": 3,
"minimum": 1,
"description": "How many calls for sku. Default 1, maximum 3."
},
"quote_id": {
"type": "string",
"description": "Required. A fresh quote_id from search, describe, or quote that matches this SKU, quantity, and price. A param change is accepted when the price is unchanged and still within max_total_sats. A different price returns quote_mismatch and charges nothing. A missing or stale quote returns quote_required and a fresh quote, and charges nothing. A second buy with the same quote_id returns the first result and charges nothing."
},
"total_cost": {
"type": "string",
"pattern": "^\\d[\\d,]* sats(?:\\s*\\([^)]*\\))?$",
"examples": [
"53 sats (~$0.06 USD)"
],
"maxLength": 200,
"minLength": 1,
"description": "All-in price from search or describe, shown before approval. One price in sats and local currency. Do not put a balance in this string. Example: 53 sats (~$0.06 USD). For a basket, one total for every item. (minimum length 1, maximum length 200)."
},
"accept_terms": {
"type": "string",
"description": "Required. Copy accept_terms from the example buy call. The current terms version, plus the partial-credit token when the listing is marked Partial credit only. A missing value returns terms_required and charges nothing."
},
"max_total_sats": {
"type": "integer",
"minimum": 1,
"description": "Maximum all-in sats for this buy, from totalSats. For a basket, the sum. The server rejects the buy and does not pay if the real total is higher. (minimum 1)."
},
"idempotency_key": {
"type": "string",
"description": "Optional client key. The same key returns the first result and charges nothing."
},
"confirm_duplicates": {
"type": "boolean",
"description": "Set true only to buy the same line more than once. Otherwise a repeated line is refused and nothing is charged."
},
"simulate_balance_sats": {
"type": "integer",
"minimum": 0,
"description": "Dry run only. Pretend the credit balance is this many sats. Ignored unless dry_run is true. Use 0 to force insufficient_balance without spending."
},
"simulate_auto_approve_sats": {
"type": "integer",
"minimum": 0,
"description": "Dry run only. Pretend auto-approve is this many sats. Ignored unless dry_run is true. Use 0 to force approval_required without spending."
}
},
"description": "Required once: total_cost, max_total_sats, quote_id, and accept_terms. Pass sku for one task, or items for a basket. dry_run true runs the limit, approval, and balance checks and returns that code without spending. simulate_balance_sats and simulate_auto_approve_sats apply only on a dry run."
}