Skip to main content

API Documentation

Create Order​

POST
https://api.garden.finance/orders
Create a new order

Payload​

FieldTypeDescription
sendAddressstringWallet address in source chain
receiveAddressstringAddress where funds should be received in destination chain
orderPairstringThe trading pair for the order (explained here)
sendAmountstringAmount to be sent in satoshi (sats)
receiveAmountstringAmount to be received in satoshi (sats)
secretHashstringHash of the secret generated by the user, which the counterparty will use to lock their funds in the HTLC
userWalletBTCAddressstringBTC wallet address where funds should be redirected from the receive address
note

The sendAmount and receiveAmount must be in their lowest denominations. For example, if you want to send 0.001 Bitcoin then the sendAmount would be 100000 SATS.

Authentication:
Include an Authorization header with your request. Learn how to obtain an auth token here.

Garden charges 0.3% as the swap fees. Fee is calculated as the difference between the input and output amounts, which should be greater than or equal to 0.3% of the input amount.

Response​

FieldTypeDescription
orderIDuintID of the created order

Example payload

{
  "sendAddress": "",
  "receiveAddress": "",
  "orderPair": "bitcoin:primary-ethereum:0xa5e38d098b54c00f10e32e51647086232a9a0afd",
  "sendAmount": "100000",
  "receiveAmount": "99700",
  "secretHash": "",
  "userWalletBTCAddress": ""
}

Get Order​

GET
https://api.garden.finance/orders/:id
Retrieve the details of an order by its ID

Order Object​

  • Initiator: The party who creates the order.
  • Follower: The party who accepts the order, also known as the counterparty or Filler.
FieldTypeDescription
makerstringAddress of the maker who created the order
takerstringAddress of the taker who accepted the order
orderpairstringThe trading pair for the order (here)
initiatoratomicswapiduintID of the initiator's atomic swap
followeratomicswapiduintID of the follower's atomic swap
initiatoratomicswap*atomicswapDetails of the initiator's HTLC
followeratomicswap*atomicswapDetails of the follower's HTLC
secrethashstringHash of the secret generated by the initiator, which the initiator and follower will use to lock their funds in the HTLC
secretstringThe secret generated by the initiator, revealed during redemption process
pricefloat64The price ratio of the initiator's atomic swap amount to the follower's atomic swap amount
statusuintThe current status of the order
secretnonceuint64A count of the user's number of orders, used as a nonce to generate secrets
userbtcwalletaddressstringUser's BTC wallet address

AtomicSwap Object​

FieldTypeDescription
statusuintThe current status of the atomic swap
secretHashstringHash used in the HTLC to lock the funds
secretstringSecret used to unlock the HTLC, revealed during the redemption process
onChainIdentifierstringOn-chain identifier for the generated HTLC
initiatorAddressstringAddress of the initiator providing funds into the HTLC.
redeemerAddressstringAddress where funds will be transferred if the HTLC is successfully unlocked.
timelockstringTime lock for the atomic swap
chainchainThe blockchain where the atomic swap is executed
assetassetThe asset being swapped
amountstringThe amount to be filled in HTLC
filledAmountstringThe amount filled in the HTLC
initiateTxHashstringTransaction hash of the initiation transaction
redeemTxHashstringTransaction hash of the redemption transaction
refundTxHashstringTransaction hash of the refund transaction
priceByOraclefloat64Price of the token involved (BTC or WBTC)
minimumConfirmationsuint64Minimum number of blockchain conformations required
currentConfirmationsuint64Current number of confirmations
initiateBlockNumberuint64Block number of the initiation transaction

Every order involves two parties and two corresponding atomic swaps. The initiator initiates in their own initiator atomic swap and redeems funds from the follower atomic swap. Similarly, the follower initiates in their follower atomic swap and redeems in the initiator atomic swap. Refunds occur within the same atomic swap; for instance, the initiator redeems in their own initiator atomic swap.

note
  • To find the initiate transaction of the initiator, use the initiate transaction hash from the initiator atomic swap.
  • To find the redeem transaction of the initiator, use the redeem transaction hash from the follower atomic swap.
  • To find the refund transaction of the initiator, use the refund transaction hash from the initiator atomic swap.

Example

{
  "ID": 8086,
  "CreatedAt": "2024-01-16T00:18:11.350761Z",
  "UpdatedAt": "2024-01-18T17:52:27.605397Z",
  "DeletedAt": null,
  "maker": "0xaf0fdd39e5d92499b0ed9f68693da99c0ec1e92e",
  "taker": "0xb9c43f86e153acc31e4ae39fde1f5887e05f8d51",
  "orderPair": "bitcoin-ethereum:0xA5E38d098b54C00F10e32E51647086232a9A0afD",
  "InitiatorAtomicSwapID": 16171,
  "FollowerAtomicSwapID": 16172,
  "initiatorAtomicSwap": {
    "ID": 16171,
    "CreatedAt": "2024-01-16T00:18:11.167048Z",
    "UpdatedAt": "2024-01-18T17:52:27.319582Z",
    "DeletedAt": null,
    "swapStatus": 5,
    "secretHash": "",
    "secret": "",
    "onChainIdentifier": "bc1qptjlcdqjx92rate7aylgm55zvtt84k0ng4z0z0x5pjd29hvmpp6sc5mq7c",
    "initiatorAddress": "1PCDCnwG39jnHQ9YRmB1MrCx1wFNMT5qjB",
    "redeemerAddress": "bc1q6ladqd8xssdkvp0re7mzyuz5gjtmea4sjlx8sl",
    "timelock": "288",
    "chain": "bitcoin",
    "asset": "primary",
    "amount": "55000000",
    "filledAmount": "55000000",
    "initiateTxHash": "c0926a24c8838c3d2aef8d021138113a3b551fbe98e29a2bc7f6edfe6da44f32",
    "redeemTxHash": "",
    "refundTxHash": "5407728e50158c04ceff8b79821724ab1f365bb27a95d70d9d3510b68535495f",
    "priceByOracle": 43020.05493015489,
    "minimumConfirmations": 4,
    "currentConfirmation": 4,
    "initiateBlockNumber": 825951
  },
  "followerAtomicSwap": {
    "ID": 16172,
    "CreatedAt": "2024-01-16T00:18:11.213118Z",
    "UpdatedAt": "2024-01-18T17:52:27.176631Z",
    "DeletedAt": null,
    "swapStatus": 5,
    "secretHash": "",
    "secret": "",
    "onChainIdentifier": "dc609bcc0ac9748cb555f0376a079588e1ee3e6b8aaeb91442ef47666de267e6",
    "initiatorAddress": "0xb9C43F86E153acc31e4aE39fDE1f5887e05F8D51",
    "redeemerAddress": "0xaf0FDd39e5D92499B0eD9F68693DA99C0ec1e92e",
    "timelock": "7200",
    "chain": "ethereum",
    "asset": "0xA5E38d098b54C00F10e32E51647086232a9A0afD",
    "amount": "54835000",
    "filledAmount": "",
    "initiateTxHash": "0x6c632a407fe8bb000b9305023f3fdd087cf8d7754c06ad98befddcde00711899",
    "redeemTxHash": "",
    "refundTxHash": "0x88ef6f80cc6ed44c3d759aaeb0ddaa712c7d9a5288f031f04ff38c70dc5fa757",
    "priceByOracle": 43020.05493015489,
    "minimumConfirmations": 12,
    "currentConfirmation": 12,
    "initiateBlockNumber": 19016028
  },
  "secretHash": "fd2497d28fb25d39778f376afbc9d05fe7e2eb6909d589dd74c976f92f2066a6",
  "secret": "",
  "price": 1.0030090270812437,
  "status": 4,
  "secretNonce": 15,
  "userBtcWalletAddress": "bc1qc8tyqltzmvmmdnrjvhegn9gs58688rhqu6xqp8",
}

AuthToken​

POST
https://api.garden.finance/verify
Get a auth token

This endpoint provides a JWT token that remains valid for 24 hours. To obtain the auth token, you need to send a message along with a signature that signs the message.

Payload​

FieldTypeDescription
messagestringA (SIWE) (Something I Want to Encrypt) message, which includes a random nonce and a statement for validation.
signaturestringCryptographic signature of the message field to authenticate the request.

Response​

FieldTypeDescription
tokenstringJWT token

You can use a random nonce to create a message and sign it. Alternatively, you can obtain a truly random nonce from the endpoint (nonce).

Subscribe to Orders​

WSS
https://api.garden.finance/
Subscribe to orders

To receive updates from the Orderbook, you can connect to the websocket endpoint and use the subscription texts provided below. If there are no updates, the server will send a ping message every 60 seconds to keep the connection alive. You can send multiple subscription texts in a single websocket connection to receive updates for various criteria simultaneously.

  • The ping message object is
{
  "type": "ping",
  "msg": "ping"
}

Types of subscribe texts​

  • Subscribe to updated orders: Initially provides all orders associated with the given address (this address can be either the maker's or taker's in the order object). Subsequent responses will include orders associated with the given address that have updates or are newly created.

    • Regex: ^0x[0-9a-fA-F]{40}$
    • Example: subscribe::0x3139C33b7218237Bbd22235C78078731216fD05b

  • Subscribe to pending and updated orders: Initially provides all pending orders associated with the given address (this address can be either the maker's or taker's in the order object). Subsequent responses will include orders associated with the given address that have updates or are newly created.

    • Regex: ^0x[0-9a-fA-F]{40}-onlyPending$
    • Example: subscribe::0x3139C33b7218237Bbd22235C78078731216fD05b-onlyPending

  • Subscribe to order updates: This will take an orderId in the subscribe text and only respond/send updates if there is an update in that order.

    • Regex: ^[0-9]+$
    • Example: subscribe::20000

  • Subscribe to open orders: This subscription takes a chain name and direction as input and sends all newly created orders in that direction.

    • Regex: ^[a-zA-Z_]+(:0x[0-9a-fA-F]{40})?-[a-zA-Z_]+(:0x[0-9a-fA-F]{40})?
    • Example: subscribe::bitcoin-ethereum
    • In the above example, clients will receive all orders created in the direction between Bitcoin and Ethereum.

    For more information about supported chains, visit supported-chains.

note

Regex is valid for the text after subscribe::

Response Types​

Subscription TypeResponse Structure
Updated Orders
{
  "type": "rest.UpdatedOrders",
  "msg": {
    "orders": [],
    "error": "string"
  }
}
Pending and Updated Orders
{
  "type": "rest.UpdatedOrders",
  "msg": {
    "orders": [],
    "error": "string"
  }
}
Order Updates
{
  "type": "rest.UpdatedOrder",
  "msg": {
    "order": {},
    "error": "string"
  }
}
Open Orders
{
  "type": "rest.OpenOrders",
  "msg": {
    "orders": [],
    "error": "string"
  }
}
Error
{
  "type": "rest.WebSocketError",
  "msg": {
    "code": "int",
    "error": "string"
  }
}
note

The orders in the table above are of type Order.

Fill Order​

PUT
https://api.garden.finance/orders/:id
Fill an order

This API endpoint is used to fill an order. You can get all newly created orders by subscribing to orders and then fill an order using this endpoint.

You must stake 210,000 SEED to be eligible to fill an order.

Payload​

FieldTypeDescription
sendAddressstringAddress from which Filler will deposit funds
receiveAddressstringAddress where Filler wants to receive funds

Authentication: Include an Authorization header with your request. Learn how to obtain an auth token here.

Assets​

GET
https://api.garden.finance/assets
Get all the supported assets and chains

The assets endpoint returns a JSON object listing all supported chains along with their associated assets available for trading on Garden. Each key in the JSON represents a blockchain supported by Garden, and the corresponding array lists the specific assets available for trading within that blockchain.

Sample response

{
 "bitcoin": [
   "primary"
 ],
 "bitcoin_testnet": [
   "primary"
 ],
 "ethereum": [
   "0xA5E38d098b54C00F10e32E51647086232a9A0afD"
 ],
 "ethereum_arbitrum": [
   "0x203DAC25763aE783Ad532A035FfF33d8df9437eE"
 ],
 "ethereum_sepolia": [
   "0x130Ff59B75a415d0bcCc2e996acAf27ce70fD5eF"
 ]
}

Nonce​

GET
https://api.garden.finance/nonce
Get random nonce

The nonce endpoint provides a randomly generated string of length 16.

Response​

FieldTypeDescription
noncestringA random string of length 16.