Auto-ticket partner deposit addresses
An auto-ticket partner deposit address is a Bitcoin address with a ticket rule attached to it. You create the address, show it to a customer, and ask them to pay in BTC. Once that payment has enough confirmations, Luckotto applies the rule and uses the payment to create a funded ticket automatically.
This is useful when the customer should fund the Luckotto ticket directly. Your server creates the address at the start of checkout, but it does not need to make a second ticket-purchase request after the payment arrives. You still own the checkout, customer account, retail price, and any rules for distributing a prize.
A payment address that completes the ticket purchase.
A normal partner deposit address adds a confirmed payment to your Luckotto balance. Your server must later spend that balance through a separate ticket request. An auto-ticket address combines those two steps: the confirmed payment itself triggers the ticket attempt.
The address is the customer's payment destination
Create a fresh address when checkout begins and show its Bitcoin address or QR code to the customer. The customer must pay in BTC, and their ticket does not exist until the payment reaches the required confirmation depth.
The address remembers how its payments should be split
The address stores one immutable allocation rule. It might place the whole net payment into the ticket, use a percentage, or cap the ticket at a fixed amount and leave the rest as partner balance. Every payment received by that address uses the same rule. The expression reference is where that rule's exact language and arithmetic are documented.
The partner still owns the customer relationship
Luckotto records the Bitcoin payment and creates the underlying ticket. Your product decides what the customer sees, how retail pricing works, and how any partner prize is distributed. Use private address metadata to connect the Luckotto address to your own order.
From checkout to ticket.
The address is created once. Every Bitcoin transaction output later sent to it is treated as a separate payment and processed with the same frozen rule.
Create an address for the payment
Create a partner deposit address through the dashboard or the partner API. Include an
autoTicket.expressionin the request. The returned Bitcoin address is the address you present to the customer.Address creation is idempotent. Use a UUIDv4 id for the request and retry the exact same request when you need to recover the same address. For a checkout integration, a fresh address for each expected payment makes reconciliation and on-chain privacy clearer.
Wait for the customer's BTC payment
A payment seen in the mempool is not yet a Luckotto ticket. Show it as pending until it reaches the current auto-ticket confirmation depth. Read that value from the public constants endpoint because it can differ between environments and may change over time.
Luckotto allocates the confirmed payment
Luckotto subtracts the deposit fee from the received amount. It then applies the address's stored allocation rule. The rule determines the ticket budget, and any unused net amount becomes partner balance. The expression reference explains the exact variables, language, arithmetic, and validation.
Read the recorded outcome
Poll the authenticated deposit-address detail or deposit event stream until the payment has a terminal auto-ticket result. A successful result contains the ticket id, allocated amount, and balance remainder. Use that result to update the customer's order in your own system.
A confirmed payment does not always create a ticket.
Luckotto records one terminal result for each received output. If a ticket cannot be created, the customer's net payment is not discarded; it becomes partner ticket balance instead.
created
The expression returned a valid budget greater than the ticket fee. Luckotto charged the ticket fee, used the rest of the budget as the ticket contribution, and credited any unused net amount to partner balance.
skipped_too_small
The expression returned a valid budget at or below the ticket fee, so there was no positive contribution with which to create a ticket. The entire net payment was credited to partner balance.
skipped_invalid_result
The stored allocation rule did not produce a usable ticket budget. No ticket was created, and the entire net payment was credited to partner balance.
The address remains live after checkout.
Bitcoin addresses cannot be recalled after you hand them out. Luckotto continues monitoring old partner deposit addresses, and every later payment to an auto-ticket address runs the same expression again.
Use one address for one expected payment
Stop showing the address once you have received the expected payment, but continue to handle accidental duplicate or late sends. Each received output makes its own ticket attempt; an address is not automatically closed after the first one.
The ticket rule cannot be edited
The allocation rule and auto-ticket metadata are fixed when the address is created. If the price, allocation, or public metadata needs to change, create another address. Replaying the same UUID with different values is rejected rather than silently changing the existing address.
Keep private customer data out of the ticket
The top-level address metadata is private to the partner and is suitable for an internal order reference. The autoTicket.metadata value is different: it is copied to every ticket created by the address. When the round seals, only its plain canonical-JSON SHA-256 is persisted in the partner manifest. Both metadata objects have a 4 KiB canonical JSON limit, and the complete mutation body has a 16 KiB limit. Do not place names, email addresses, or other sensitive data in public ticket metadata.
A created ticket is not taken back.
An auto-ticket outcome is terminal. If the Bitcoin output that funded a created ticket is later removed by a chain reorganization, the Luckotto ticket remains valid. Luckotto reverses the corresponding balance credit instead, which can leave the partner with a negative balance.
This is why Luckotto waits for the configured auto-ticket confirmation depth before creating the ticket. A partner may wait longer before treating the customer's payment as final in its own product, but it should never claim that an unconfirmed payment has already created a Luckotto ticket.
Create, test, and monitor.
The API reference defines the exact creation request, idempotency rules, response fields, and deposit event states. Test the allocation expression before creating an address, then use the authenticated deposit response as the source of truth for whether a ticket exists.