> For the complete documentation index, see [llms.txt](/llms.txt)

# KioskTransaction

Build kiosk transactions for listing, purchasing, and managing items on Sui.



`KioskTransaction` is the client to build transactions that involve Kiosk. It's used similar to
`Transaction`, and helps in building a transaction.

You need to instantiate it once in every Programmable Transaction Block (PTB) that you're building.

There are two flows to follow, the first being managing an existing kiosk, and the second is
creating a new one. It hides all the complexity between a personal and a non-personal kiosk.

## Using an existing kiosk

If you have already retrieved a kiosk from `client.kiosk.getOwnedKiosks()`, you can pass a cap.

> You must always call `kioskTx.finalize()` before signing and executing the transaction, as your
> last command.

```typescript
const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0xMyAddress' });

const tx = new Transaction();
const kioskTx = new KioskTransaction({
	transaction: tx,
	kioskClient: client.kiosk,
	cap: kioskOwnerCaps[0],
});

// Now you can do whatever you want with kioskTx.
// For example, you could withdraw the profits from the kiosk.
kioskTx.withdraw('0xMyAddress', 100_000_000n);

// You could also chain some other functionality if you want to.
kioskTx
	.place({
		itemType: '0xMyItemType',
		item: '0xMyItem',
	})
	.list({
		itemType: '0xMyItemType',
		itemId: '0xMyItem',
		price: 10000n,
	});

// Always called as our last kioskTx interaction.
kioskTx.finalize();

// Sign and execute transaction.
await signAndExecuteTransaction({ tx: tx });
```

## Creating a new kiosk

If you don't have a kiosk yet, you can create one using `create()`. The `KioskTransaction` enables
use of the newly created kiosk to execute some functionality in the same PTB.

```typescript
const tx = new Transaction();
const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });

// Calls the creation function.
kioskTx.create();

// We can use the kiosk for some action.
// For example, placing an item in the newly created kiosk.
kioskTx.place({
	itemType: '0x...::hero::Hero',
	item: '0xAHero',
});

// Shares the kiosk and transfers the `KioskOwnerCap` to the owner.
kioskTx.shareAndTransferCap('0xMyAddress');

// Always called as our last kioskTx interaction.
kioskTx.finalize();

// Sign and execute transaction.
await signAndExecuteTransaction({ tx: tx });
```

## Creating a new personal kiosk

`KioskTransaction` makes it easy to create a new personal kiosk, and use it in the same PTB.

```typescript
const tx = new Transaction();
const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });

// An example that creates a personal kiosk, uses it to place an item, and shares it.
// The `PersonalKioskCap` is automatically transferred to the sender when calling `.finalize()`.
// The `Kiosk` is automatically shared when calling `.finalize()`.
kioskTx
	.createPersonal(true) // `true` allows us to reuse the kiosk in the same PTB. If we pass false, we can only call `kioskTx.finalize()`.
	.place({
		itemType: '0x...::hero::Hero',
		item: '0xAHero',
	})
	.finalize(); // finalize is always our last call.

// Sign and execute transaction.
await signAndExecuteTransaction({ tx: tx });
```