Skip to main content

Offers tutorial (GUI)

This tutorial covers Chia offers using the official wallet's graphical user interface.

See also our command line tutorial and our reference document.

Note: This tutorial occasionally references a token called "CAT King Cole" (CKC). This token is for demonstration purposes only.

Contents:#


Add a new CAT wallet#

In order to create an offer, you must have a wallet for any Chia Asset Tokens (CATs) you want to acquire. If you don't have such a wallet, it's easy to add one.

For example, here's how to add the Stably USD (USDS) token:

  1. Click "+ ADD TOKEN".
XCH balance before offer

  1. Click the "USDS / Stably USD" button.
Add USDS wallet

  1. "Adding USDS token" will be displayed while your new wallet is being created. This will take some time.
Add USDS wallet

  1. You now have a USDS wallet, in addition to your standard Chia wallet.
Two wallets

Create a single-token offer#

In this example, we'll offer 0.1 XCH in exchange for 10 USDS.

  1. Click "MANAGE OFFERS".
Add USDS wallet

  1. Click "CREATE AN OFFER".
Create offer

  1. The "Create an Offer" dialog will appear. When you select an asset type to be offered, the dialog will display your spendable balance. After you have filled in the details of your offer, you will also be shown the exchange rate of the assets you want to trade, using the values you have entered.

    When you are satisfied with your offer, click "SAVE OFFER".
Save offer

  1. Choose a name and location for your offer file.
    (Depending on your operating system, this dialog may appear different to what is shown.)
Save offer

  1. A new dialog will appear, suggesting a few locations to share your offer. This is strictly optional. You could also directly share your offer file with a friend, or on social media, or anywhere else you want.

    That said, for this tutorial we'll click the "OFFERBIN" button.
Share offer

  1. You will be shown the details of your offer once again. Click the "SHARE" button to share your offer.
Share on offer bin

  1. Your offer has now been shared on Offer Bin, a website dedicated to sharing Chia offers. Offer Bin is not affiliated with Chia Network Inc.

    You now have the option to view your offer on Offer Bin, copy the URL to share in more locations, or simply wait for someone to accept your offer.
View on offer bin

  1. There is now one offer in the "Manage Offers" dialog. Its status is "Pending Accept".
Pending accept

Congratulations! You have created an offer. A few things to note:

  • Your wallet has reserved the coin(s) necessary to complete the offer.
  • The blockchain has not recorded this offer.
  • You can distribute the offer file wherever you want.
  • Anyone who sees the offer file can attempt to accept it.

Accept a single-token offer#

This example will use a different computer to accept the offer that was created in the previous example. Keep in mind, offers are accepted on a first-come, first-served basis.


1. From your light wallet's main dialog, click "MANAGE OFFERS".
Chia wallet

  1. Click "VIEW AN OFFER".
View an offer

  1. You can either paste the contents of an offer file, or load the whole file. In this example, we'll do the latter.
Select offer file

  1. A new dialog will open. This may look different than what is pictured, depending on your operating system.

    Find the offer file and click "Open". Keep in mind, the name of the offer file doesn't necessarily reflect the actual offer.
Open

  1. You'll be shown a summary of the offer. You can add an optional fee (payable in XCH) if you want Chia's blockchain to prioritize your offer. If you agree with the terms, click "ACCEPT OFFER".
Accept offer

  1. You'll be given a chance to cancel your acceptance of the offer. Click "ACCEPT OFFER" to continue.
Accept offer

  1. After a few seconds, you'll receive a "Success" message. This means the offer has been completed and sent to the blockchain for confirmation.
Success

  1. The offer is now in the "Pending Confirm" state.
Pending confirm

  1. The offer will take a few minutes to be confirmed. Note that this time can vary, depending on how full the mempool is and whether you included a fee upon accepting the offer.
Confirmed

  1. After the offer has been confirmed, your new balance will be shown in your wallet.
Wallet post trade

Cancel an offer#

You can cancel any offer you created, as long as it has not already been accepted.

  1. In the "Manage Offers" dialog, locate the offer you want to cancel. It must be in the "Pending Accept" state.

    Click the three dots in the "Actions" column.
Offer actions

  1. Click "Cancel Offer".
Cancel an offer

  1. The "Cancel Offer" dialog will appear. The default option is to cancel on the blockchain. This option will use your wallet to spend the coins you had offered, and create new coins of the same type and value. This process does not involve taking the other end of the offer, so you will not receive any funds of the type you had requested. The end result is that your wallet's balance will be the same as it was before you made the offer (minus any transaction fees).

    The advantage of canceling in this manner is that it ensures that nobody can accept your offer in the future. The disadvantages are that you will need to wait a few minutes for your transaction to be processed, and that you may have to pay a transaction fee.

Cancel on chain

  1. If you uncheck the checkbox, your wallet will un-reserve the coins for your offer. However, nothing will be recorded on the blockchain. If you have copied your offer file elsewhere, someone could still accept it.

    The advantages of this option are that it will cancel your offer instantly, and there's no need to include a fee.

Cancel off chain

  1. If you left the checkbox checked in the previous step, your offer will enter the "Pending Cancel" state while the cancellation is being recorded on the blockchain. This could take several minutes.
Pending cancel

  1. When your order has been successfully canceled, it will enter the "Cancelled" state. Your funds are now available in your wallet.
Cancelled

Create a multiple-token offer#

It's easy to create an offer with multiple tokens, on one or both ends of the trade.

  1. In the "Create an Offer" dialog, click the "+" to add more tokens. In order for the "+" to be accessible, you must have a wallet with a token that has not been used in this offer.
Plus buttons

  1. When you are satisfied with the number of tokens being offered and received, click "SAVE OFFER".
Save multiple offer

  1. Your new offer, including all tokens, is now in the "Pending Accept" state.
Manage multiple offer

You now free to share your offer file anywhere you wish, just as you were with the single-token offer.


Accept a multiple-token offer#

  1. The process to accept a multiple-token offer is the same as for a single-token offer.
Multiple accept dialog

  1. The confirmation dialog shows all assets involved in the offer.
Multiple confirmation dialog

  1. After accepting the offer, a new wallet will be created for any tokens the Taker didn't already have.
CKC wallet
USDS wallet

Potential issues#

This section will detail a non-comprehensive list of issues you might encounter while making or taking offers.

Contents:#


Maker doesn't have enough money#

Let's say a Maker has wallets for XCH and CKC, with no money in either of them.

0 XCH wallet
0 CKC wallet

The maker attempts to make an ambitious offer: 100 XCH for 1 million CKC.

Offer 100 XCH for 1 million CKC

However, the Maker does not have enough money to create this offer. As a result, an Error is displayed:

Amount exceeds spendable balance

Taker doesn't have enough money#

Let's say the Taker has a wallet with no money in it:

0 XCH wallet

And there's an outstanding offer requesting 0.1 XCH for 10,000 CKC:

Accept offer

However, the Taker does not have enough money to accept this offer. As a result, an Error is displayed:

Insufficient funds

Taker accepts an unknown CAT offer#

You should be extra careful before accepting offers for unknown CATs. This is because the offer might be a scam where a different -- and worthless -- token is actually being offered.

Here's how the scam would work:

Let's say a potential Taker has 0.1 XCH in their wallet.

0.1 XCH wallet

There is an offer of 0.25 Shibe (an unknown CAT) in exchange for 0.1 XCH.

Here's the offer from the Taker's perspective:

Offer shibe for XCH

The Taker decides to accept the offer.

There is a warning dialog about the unknown cat, after which the offer is confirmed successfully:

Unknown CAT warning
Unknown CAT success

Notice that the offer file was named 0.25_Shibe_for_0.1_XCH.offer, but the file name itself does not dictate the contents of the offer. The Taker may have inadvertently accepted an offer for a worthless token!

Luckily, it is easy to avoid this scam by cross-referencing the unknown CAT's ID before accepting the offer. In this case, the Taker should verify from a trusted source that 4ac6a35e5fecb50d85604b19250a942afdc81876fe11db1f9d970c95dcf2c43f indeed corresponds to Shibe.

Chia does install a list of known CATs by default, so this scam should be rare, but you should always be diligent in scrutinizing offers for unknown CATs.


Taker attempts to accept an invalid offer#

If the Maker has canceled the offer on the blockchain, or a Taker has already taken the offer, it is no longer valid.

Any potential Takers will be conveyed this information upon viewing the offer. For example:

Invalid offer

Maker cancels an offer locally, Taker accepts the offer#

This example will demonstrate that if you need to cancel an offer, you should always do so on-chain unless you are certain the offer file has not left your computer.

Let's say a Maker has 0.1 XCH and 1 USDS:

0.1 XCH in wallet
1 USDS in wallet

The Maker offers 0.1 XCH in exchange for 10 USDS:

Offer 0.1 XCH for 10 USDS

The Maker then decides to cancel the offer, and unchecks the "Cancel on blockchain" checkbox:

Cancel offer off chain

The offer's state is immediately changed to "Cancelled".

Canceled offer off chain

After the offer has been canceled, a Taker notices the offer file and decides to accept it:

Accept a canceled offer
Confirm a canceled offer

Later, the Maker notices that the offer has gone through, despite having been canceled:

Post-offer 0 XCH
Post-offer 11 USDS

If the offer had been canceled on-chain, the reserved coins would have been spent. At that point, even if someone else had gotten access to the offer file, the offer itself would've been invalid.

The lesson here is do not uncheck the "Cancel on blockchain" checkbox unless you're certain the offer file has never left your computer.


Whole coins must be reserved#

Under the coin set model, coins can be of any value. When an offer is created, the Maker's wallet must reserve enough coins to meet the requirements of the offer.

The coin set model has many advantages over the account model, but it can create some situations that take time to understand.

For example, let's say a Maker has 1 XCH and 0 USDS:

1 XCH in wallet
0 USDS in wallet

The Maker creates an offer of 0.1 XCH for 10 USDS.

The Maker received the XCH in one lump sum, so there is a single coin worth 1 XCH in the Maker's wallet.

This is viewable in the offer's details:

Offer in Pending Accept state
Show offer's details
One coin used for offer
Scroll to the bottom to view coins reserved for the offer.

While the offer is pending, the Maker attempts to send 0.1 XCH to another address.

Notice that while the Total Balance is 1, the Spendable Balance is 0.

Can't send while offer pending

This should be possible -- the Maker has 0.9 XCH, even after taking the offer into account. The reason for the Exception is because the Maker only has a single coin worth 1 XCH, and that coin has already been reserved for the offer.

It's similar to using a $10 bill to buy something for $1. Before you receive your change, you can't buy anything else. On the other hand, if you had started with two $5 bills and bought the same $1 item, you could've purchased something else while waiting for your change.

The Maker can work around this issue by canceling the offer, then breaking the single large coin into multiple small ones. One simple way to do this would be to send money to him/herself:

Maker sends money to him/herself

The Maker can then recreate the same offer. The new offer's details show a coin worth 0.9 XCH being reserved:

New details of Maker's offer

The Maker's wallet shows a Total Balance of 1 XCH. This is the same as before, but there are now two coins that sum to 1 XCH.

Because there are now two coins in the Maker's wallet, and only one (worth 0.9 XCH) has been reserved for the offer, the Spendable Balance is 0.1 XCH:

Maker has 0.1 XCH available

The Maker can now send 0.1 XCH to another wallet, even while the offer is still pending:

Successful send while offer pending

One of the Maker's coins has been reserved for the offer, and the other has been sent to another wallet. The Maker can further break apart the large coin as needed.


Further reading#