Solar Swap API

Introduction#

Solar Swap is a cross-chain swap service with no accounts: a person picks a pair and an amount, sends their coins to a one-time deposit address, and an exchange pays the swapped coins straight to the address they gave. The API gives your code the same three things the site does: the coins that can be swapped, a quote, and a swap to open and follow.

There is nothing to sign up for. Call it from a server, a script or a browser (any origin may call it). Each call is handled by Solar Swap's swap service, which asks the exchange it works with and answers in the same request. Solar Swap never holds the coins: the exchange pays your payout_address directly, and Solar Swap's fee is taken by the exchange out of the swap and shown on every quote.

Conventions

Quickstart#

A swap from start to finish takes four calls. Run them as they are: the quote and the coin list are free, and nothing moves until coins are sent to the deposit address.

1. Find the codes of the two coins

   Every coin is a ticker and a network. Read the list once and keep it; it changes about hourly.

   GET /api/v1/coins

   cURLJavaScriptPython

   curl "https://solarswap.io/api/v1/coins"

2. Get a quote

   Give the pair and the amount sent. The answer says what the receiving address gets, with Solar Swap's fee already out, and both amounts in dollars.

   GET /api/v1/quote

   cURLJavaScriptPython

   curl "https://solarswap.io/api/v1/quote?coin_start=eth&chain_start=eth&amount_start=0.1&coin_end=sol&chain_end=sol"

3. Open the swap

   Add the address that receives the coins and the sender's refund address. Send a client key if you want to be able to delete the swap later. The answer is the deposit address and the exact amount to send to it.

   POST /api/v1/swap

   cURLJavaScriptPython

   curl -X POST "https://solarswap.io/api/v1/swap" \
     -H "Content-Type: application/json" \
     -H "X-Client-Key: $CLIENT_KEY" \
     -d '{
       "coin_start": "eth",
       "chain_start": "eth",
       "amount_start": "0.1",
       "coin_end": "sol",
       "chain_end": "sol",
       "payout_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
       "refund_address": "0x6b3a9c2e8f1d4a7b0c5e2f9a1b8d3c4e5f6a7b8c"
     }'

4. Send the deposit and follow the swap

   Send exactly deposit_amount to deposit_address (with deposit_memo when there is one), then read the swap every 10 to 20 seconds until its status is finished. The person can follow it at url too.

   GET /api/v1/swap/{id}

   cURLJavaScriptPython

   curl "https://solarswap.io/api/v1/swap/3f9a1c2b4d5e6f708192a3b4c5d6e7f8"

Client key#

The API has no accounts, so a swap belongs to whoever opened it only if they say who they are. That is the X-Client-Key header: 64 hexadecimal characters you generate once and keep secret, sent when you open a swap and when you delete one. A swap opened with a key can only be deleted with the same key. Opened without one, it can't be deleted by anyone, which is fine when you never need to.

The key says nothing about who you are: Solar Swap stores only a hash of it, to tell your swaps apart from everyone else's. Use one key per integration, or one per user if each of them should only be able to delete their own.

# A key, once. Keep it on your server, never in a page.
CLIENT_KEY=$(openssl rand -hex 32)

Member key#

The standard limits suit a wallet or a script serving a few people. An integration that needs more can be given a member key by Solar Swap: a string starting with solar_, sent as the X-Solar-Key header on any call. When it's a key we issued and it's still active, the limits set for it apply instead of the standard ones, and they're counted per key rather than per address: your servers' calls pool under your key and never share a limit with anyone else behind the same address.

Nothing else changes. The key isn't required and carries no account. A key we don't recognise, because it was never issued or has been revoked, simply gets the standard limits; the answer then says X-Solar-Key-Status: unknown, so a typo shows up at once. Ask for a key, or for higher limits on one, through the Support link in the footer.

curl "https://solarswap.io/api/v1/quote?coin_start=eth&chain_start=eth&amount_start=0.1&coin_end=sol&chain_end=sol" \
  -H "X-Solar-Key: $SOLAR_KEY"

Reading your limits

Every answer, with or without a key, says which limit applied and how much of it is left.

Rate limits#

Limits are per endpoint, and per calling address, or per member key when one is sent (see Member key). A quote and a swap each reach the exchange, which is why those are the tight ones; a swap's status comes from Solar Swap's own records and can be polled freely within its limit. Past a limit the answer is 429 with a Retry-After header saying how many seconds to wait.

Standard limits

A member key has a count of its own for each endpoint, in the same windows. Quote when the person changes the pair or the amount, and refresh a quote they're looking at every 20 seconds or so rather than continuously. Read the coin list once and keep it. If an integration needs more than the standard limits, ask for a member key through the Support link in the footer.

Errors#

Every error is an HTTP status outside 2xx with a JSON body of one field, error: a sentence saying what went wrong, naming the field when one is at fault. A 4xx means the request itself: fix it rather than retrying it. A 5xx means Solar Swap or the exchange didn't answer; nothing was changed, so retry after a few seconds.

{
  "error": "the amount is below our minimum of $1 (about 0.0003 ETH)"
}

Coins and networks#

A coin is identified by its ticker and its network together, because the same token lives on several: usdt on trx and usdt on eth are different coins to a swap, with different addresses and fees. Every endpoint takes the pair as coin_start, chain_start, coin_end and chain_end, all lowercase, exactly as GET /coins lists them.

The list says which coins can be sent (send) and which received (receive). Any sendable coin can be swapped to any receivable one; a pair the exchange can't do right now answers 400 from the quote. The network codes seen most often:

Addresses are checked before anything opens: EVM, Solana and TON addresses in full, others by their shape, and the exchange checks the rest before the order exists. On networks with memos or destination tags, payout_memo is part of the address: a payout without it can be lost at the receiving end.

Amounts and fees#

Amounts are decimal strings in whole coins, with up to 18 decimals. A quote values the pair at market prices, in the coin and in dollars. Solar Swap's fee of 1% is shown on every quote as fee and is already out of amount_end: nothing is added on top. The exchange's own fees and the network fee of paying the receiving address are in the quote too. The sender pays only the usual network fee of their own deposit transaction.

There is a minimum, a few dollars at market price. Below it the quote and the swap answer 400 with the minimum and roughly how much of the coin that is. Above it, any amount the exchange can take is fine.

Swap lifecycle#

A swap is a real order at an exchange from the moment it's opened. Its status is one of five words, and a swap only ever moves forward through them.

The deposit

Send exactly deposit_amount of coin_start on chain_start to deposit_address, in one transaction, with deposit_memo when it isn't null. If less arrives, the swap waits for the rest until short_deposit_until and then goes on with what arrived, swapped at the rate of that moment; POST /swap/{id}/run has it go on at once. If more arrives, the exchange swaps what arrived. A deposit that arrives after deposit_until, when one was given, is handled by the exchange under its own rules, which may mean a refund to refund_address.

Following it

Read GET /swap/{id} every 10 to 20 seconds while the status is waiting or sending, and stop at finished, failed or needs_attention. deposit_received shows the deposit landing, payout_tx and amount_sent the payment going out. The swap's page at url shows the same to the person, so you can hand them the link instead of building a status screen.

Deleting and housekeeping

A swap nothing has arrived for can be deleted by whoever opened it with a client key; its id and page answer 404 from then on. One that never receives anything is deleted on its own 12 hours after it was opened. A swap coins have arrived for can't be deleted: it goes on to its end, whatever happens on your side.

The swap object

Every endpoint that answers a swap answers these fields.

Changelog#

Support#

Questions about a swap reach the team through the Support link in the footer: give the swap's id and order_id. Questions about the API, higher limits or an integration are welcome the same way. What a swap involves, what it costs and the terms it runs under are on the legal page; by opening swaps through the API you accept them on behalf of the people you open them for.