dexie Swap API docs

dexie_swap_api.md

Swap API for Chia Tokens (CATs)

The Swap API provides instant quotes and asset swaps. It is based on Dexie’s combined offers technology, which aggregates liquidity across multiple sources. The Swap API is the easiest and fastest way to swap CATs non-custodially on Chia for the best price.

Note: Currently only CAT-XCH pairs are supported, but support for CAT-CAT pairs is planned.

Swapping Assets Process

Swapping assets involves two steps:

1. Quote: Get a quote for the swap you want to make.
2. Swap: Execute the swap by submitting an offer for the received quote.

💰 Tip: To earn fees for facilitating swaps, integrators can add a fee destination address in Step 2.

Step 1: Get Quote

GET https://api.dexie.space/v1/swap/quote

Query Parameters

Query Parameter	Required	Possible Values	Notes
from	yes	XCH Asset Code (SBX, ...) or Asset ID (db1a...)	The asset you want to sell
to	yes	XCH Asset Code (SBX, ...) or Asset ID (db1a...)	The asset you want to buy
from_amount	no	integer (mojos)	Amount of the asset you want to sell. Default: 1000000000000 = 1 XCH; 1000 = 1 DBX. Important: Amount is in sell currency
to_amount	no	integer (mojos)	Amount of the asset you want to buy. Default: same as above. Important: Amount is in buy currency

Response

Response Value	Type	Notes
success	boolean	Indicates success
quote	object	Quote Object
from	string	The Asset ID to sell.
from_amount	integer	The amount to sell in mojos.
to	string	The Asset ID to buy.
to_amount	integer	The amount to buy in mojos.
suggested_tx_fee	integer	The suggested transaction fee in mojos. It is recommended to add this fee to the offer in Step 2.
combination_fee	integer	Combination fee charged by Dexie in basis points (already included in the quote)

Example Response

Get a quote to buy 100 DBX with XCH: curl 'https://api.dexie.space/v1/swap/quote?from=XCH&to=DBX&to_amount=100000'

{
  "success": true,
  "quote": {
    "from": "xch",
    "from_amount": 107980923348,
    "to": "db1a9020d48d9d4ad22631b66ab4b9ebd3637ef7758ad38881348c5d24c38f20",
    "to_amount": 100000,
    "suggested_tx_fee": 500000,
    "combination_fee": 100
  }
}

Use the provided from_amount and to_amount values to create an offer and submit it in Step 2.

Step 2: Execute Swap

POST https://api.dexie.space/v1/swap Content-Type: application/json

Post Parameters

Post Parameter	Required	Possible Values	Notes
offer	yes	Offer	The offer according to the quote from Step 1. It is recommended to include a transaction fee and offer expiration
fee_destination	no	xch1...	An address for receiving a share of the swap fees (0.5% of combined offer amount or 0.15% of routed AMM amount). Fees include a small buffer for price changes and can vary slightly

Response

Response Value	Type	Notes
success	boolean	Indicates success
id	string	Base58 encoded SHA256 Offer Hash
offer	full offer object	For details see examples

Example Response

Execute swap by submitting an offer:

curl -X POST -H 'Content-Type: application/json' -d '{"offer":"offer1qqz83wcsltt6wcmqvpsxygqqwc7hynr6hum6e0mnf72sn7uvvkpt68eyumkhelprk0adeg42nlelk2mpafs8tkhg2qa9qmxpk8znee5xnfq4edmh0ndpyerkh6k2kw3r06amc8mhdfde2ukhre430gyjsvym5x60jsk9afzcujmrpuhcx8lp62k6202ljnklhfm0nu05zdhvht8lkucmew9j2jqqzmy0g0dja7dzmqp570l90q5fe09td3gmns7uvh85advvjalug79jnz8xe8fe2xsaha22acaazhfmt97x0pmglj7mghdy70lfk450ulnpuxalyhvcyc5gdv39wgau5y7d4lqcd4lgcd3lg6d3lg7d3lg7d3llq948usq27uz7d7e7y77xkmf5mcmrwvn2gthfzkxx75q7vu7hqmrw6r8vmfwj8264q42mvn8ruzskxlaklvrfwfyx87ch3j83dt4crhtkcpkrjk6jvreexejdv959tq2ucyx7w4tyvzpn0dzx8f7qch9m0fekynqefu6c8hstrx2uj3haptrg4yhdtxft5xf8qfn5eddwm04pzd59dxjmgk08madexcfrjqsqxx3qake07zcgxhcladasdskneuylkppfp22q7dwrkeketuykp0w8y9a5tkngc4fernrvy68sc5vfqd06e43t03edu5hmh7zlta5vsdqt2dhlzluvkua7lehmegpql9r0vma35478283kultt84zh4u5824ew83f4n8cz23jl7l6pa7tq70c0k34rg00stvazl6q9n0sfkmg3l4frkdlhe7cds4kv6rwv6q6fl0l30ny00mg2z6x4rdlmlc8e4evhhm5cuc0xve772emxk3lhatplzlkag5tl7tucjal70p85ymy52v72tk3ccvcl4xdnvwjm4g77mwf60yt2k50zqmf78l6mlqthzqkakmsw9fvlw29g0mlkat8xvvv7dvml8tkec06a8c6n5tmlfj3d46ujw5kepx6g659ranlsyskdktljmgzxtyp4ze4aar8wjnv7ltl886m2s8v4z6uvnylaeyyu7232t66vu9tutgsdwteg7ctxsxpx9rwgl3e46jamjmv3czld0ame4tflxtr6mwresff0xlxhq7ucz3mwxflc4cthufvn3n6w7pkresuhlh8slv4l0g58m2kd4knkds664ehsn770tjulalw7y30fd6hl3lnnlvlju8m8cxm7274xk43s4lkkc5vh2dav0mgqptjqg7ggwmv9c"}' https://api.dexie.space/v1/swap`

Example Swap Response:

{
  "success": true,
  "id": "B18UHqaJXBDu8PVBWsY73opqmCszRnT8hEPmL6rYDcYa",
  "offer": {
    "id": "B18UHqaJXBDu8PVBWsY73opqmCszRnT8hEPmL6rYDcYa",
    "status": 1,
    "date_found": "2022-08-06T07:30:21.468Z",
    "date_completed": null,
    "date_pending": "2022-08-06T07:30:21.468Z",
    "date_expiry": "2022-08-06T08:30:21.468Z",
    "block_expiry": null,
    "spent_block_index": null,
    "price": 79000,
    "offered": [
      {
        "id": "a628c1c2c6fcb74d53746157e438e108eab5c0bb3e5c80ff9b1910b3e4832913",
        "code": "SBX",
        "name": "Spacebucks",
        "amount": 79000
      }
    ],
    "requested": [
      {
        "id": "xch",
        "code": "XCH",
        "name": "Chia",
        "amount": 1
      }
    ],
    "mempool": {
      "combined": true,
      "cost": 2522862972,
      "fees": 0,
      "id": "0x2d4aad0f03d92f7c288797356ad5eaa748da81a0713e4fedc4baff3f28add018"
    },
    "fees": 0
  }
}

Supported Tokens

All CAT/XCH pairs with at least one AMM liquidity pool (e.g., TibetSwap) are supported. To get a list of supported tokens: GET https://api.dexie.space/v1/swap/tokens No query parameters required.

Response Structure:

Response Value	Type	Notes
success	boolean	Indicates success
tokens[]	array	Array of supported tokens
id	string	Token Asset ID
name	string	Token Name
code	string	Asset Currency Code
denom	integer	Token Denominator (mojos)
icon	integer	URL to token icon

Example Response

curl https://api.dexie.space/v1/swap/tokens

Example Response:

{
  "success": true,
  "tokens": [
    {
      "id": "a628c1c2c6fcb74d53746157e438e108eab5c0bb3e5c80ff9b1910b3e4832913",
      "name": "Spacebucks",
      "code": "SBX",
      "denom": 1000,
      "icon": "https://icons.dexie.space/a628c1c2c6fcb74d53746157e438e108eab5c0bb3e5c80ff9b1910b3e4832913.webp"
    },
    {
      "id": "db1a9020d48d9d4ad22631b66ab4b9ebd3637ef7758ad38881348c5d24c38f20",
      "name": "dexie bucks",
      "code": "DBX",
      "denom": 1000,
      "icon": "https://icons.dexie.space/db1a9020d48d9d4ad22631b66ab4b9ebd3637ef7758ad38881348c5d24c38f20.webp"
    }
  ]
}

Example Flow Using Chia CLI RPC

Below is a shell script demonstrating how to get a quote, create an offer, and submit it:

#!/bin/sh
set -e

FROM_TOKEN="xch"
TO_TOKEN="db1a9020d48d9d4ad22631b66ab4b9ebd3637ef7758ad38881348c5d24c38f20"
TO_AMOUNT=10000 # 10 DBX in mojos

# Get Quote
QUOTE=$(curl -s "https://api.dexie.space/v1/swap/quote?from=$FROM_TOKEN&to=$TO_TOKEN&to_amount=$TO_AMOUNT")

FROM_AMOUNT=$(echo "$QUOTE" | jq -r '.quote.from_amount')
TX_FEE=$(echo "$QUOTE" | jq -r '.quote.suggested_tx_fee')

# Create Offer
OFFER_PAYLOAD=$(cat <<EOF
{
  "offer": {
    "$([ "$FROM_TOKEN" = "xch" ] && echo "1" || echo "$FROM_TOKEN")": -$FROM_AMOUNT,
    "$([ "$TO_TOKEN" = "xch" ] && echo "1" || echo "$TO_TOKEN")": $TO_AMOUNT
  },
  "fee": $TX_FEE
}
EOF
)

OFFER=$(chia rpc wallet create_offer_for_ids "$OFFER_PAYLOAD" | jq -r '.offer')

# Submit Offer
SWAP=$(curl -s -X POST -H "Content-Type: application/json" -d "{\"offer\":\"$OFFER\"}" https://api.dexie.space/v1/swap)

# Print Response
echo "$SWAP" | jq

Note on Failed Swaps

In certain situations, swaps might fail due to changes in quotes between request and execution. In such cases, offers revert to open status and can be taken by other market participants. To abort a failed swap, cancel or let it expire, or initiate a new swap with the same input coins.

Disclaimer

The API is provided "as is" without guarantees regarding completeness, accuracy, reliability, or warranties. Use at your own risk.