Step-by-step API calls for buying a Splinterlands card

Despite @yabapmatt putting up two useful tutorials for doing Steem Monsters market operations here and here, I still found the process of putting together a buy pretty complicated. Having figured it out, I feel like I should do a walkthrough tutorial of how to get the necessary data from the Splinterlands API and make the chain transactions. This is high-level and language-agnostic; I did it in Python, which probably made more work for myself than doing it in Javascript, but the tutorial will be in natural language.

This requires a reasonable amount of Steem programming knowledge and the ability to read from a website.

Step 1: Get the Card ID

So I'm assuming that what we're going to start with is the Card ID of the card that you want to buy. You can get this by looking on one of the web markets, where all of the listings have the ID listed, or by picking it out of a sm_sell_cards transaction on the chain, or by getting it from the complete market data found at https://steemmonsters.com/market/for_sale

Step 2: Get the card price and Market ID

With the Card ID we can look the card up in the API to find out what its price is and what its ID on the market is. (The market_id is the blockchain transaction ID of the original listing.) This is done by accessing the API like this: https://steemmonsters.com/cards/find?ids=C1-26-4PSQGW33G0 where the text at the end is the Card ID.

There are two important fields here, which are buy_price (the price in USD) and market_id (we'll use this in a minute.).

_{This is what the API call looked like when I was writing the tutorial; once somebody buys the card it will change and market_id and buy_price won't exist.}

Step 3: Get the Steem/SBD prices

Splinterlands has its own price feed for the value of Steem and SBD, which keeps the various markets synchronized. We get this from the constant API call https://steemmonsters.com/purchases/settings and the steem_price and sbd_price fields. Once you have this, you can do math with buy_price from Step 2 in order to calculate how much Steem or SBD you need to send in order to start the buying process. (Remember to truncate to three digits after the decimal to make a valid transaction.)

Step 4: Send a transfer to acquire a lock

We're now going to make a Steem transfer so that the API recognizes that we're attempting to buy a card, and makes sure that we have the right to do so before we send the Steem on to the card owner. There are more details on this in the second of Matt's posts linked above; basically it exists to make sure two people don't send Steem to the card owner at the same time.

In order to do this we make a transfer of the amount that we calculated from the Steem price and the buy_price in the previous step, with a memo formatted as sm_market_purchase: followed by the market_id we found in Step 2. So it looks like sm_market_purchase:c964035e1ce1f38db695f6c6b1569d0b1c12e286-8

Usually this transfer will be sent to a market, but it actually doesn't matter where you send it to. You can even send it to yourself. ideally you'll send it to whatever account is doing the rest of the actions starting with Step 5, whether that's the same account you're working with or another one. If you send that transaction to an existing market like @steemmonsters or @peakmonsters, you're done and you'll get your card, but they charge 5% for doing the rest of the work. So we're going to keep going.

Step 5: Get the transaction ID of the transfer we just sent

Every transfer on the Steem blockchain has a trx_id attached to it once it's published, and we need to get the one that we just created. In Javascript this is super_easy, in Python it is very much not, but either way I'm going to leave that as an exercise for you. Grab the transaction from the blockchain however you're comfortable with and get its trx_id. This is the index for the next API call.

Step 6: Verify the lock and get the necessary information to complete the sale

Conveniently all of the rest of the information we need is within the transaction API call for the trx_id we just produced. That's at https://steemmonsters.com/transactions/lookup?trx_id=58f44b6adee1fcf265159499672fd4c238115cd3 where again the mass of digits at the end are the trx_id.

_{Sorry for tiny text here, you may want to just look at it in the link above. This one should be stable.}

There's only one important field here, result, which contains a huge string that has everything we need to finish the buy. In order to use it you'll need to parse it into a JSON and then access the values within it: first we check if locked = true, which indicates that we have rights to buy the card. (For one minute, so don't dawdle too much.)

Then we're going to pull the rest of the data we need out of that string:

seller
sell_trx_id
payment
fee_percent
currency
locked_by

Step 7: Calculate the new send

If you want to make the seller happy, you can always send the full transaction amount along. (I know this because I initially forgot to type when doing my math, and 0.95=1 if you leave it an int.) But the system allows us to take a market fee for doing these later steps, and we should do that.

fee_percent from the previous step is the available market fee for this transaction, expressed in ten-thousandths, so 500 represents 5%. Multiply payment from the previous step by 1 - fee_percent/10000 to get the total amount we need to send on to the card seller. (As above, remember to truncate it to three digits after the decimal.)

Step 8: Send the final buying transaction

This is now just taking data we've acquired and turning them into a Steem transfer. The format is as follows: transfer to seller the amount you calculated in Step 7, in currency. The memo is a little more complicated, as it contains three parts: sm_market_sale: followed by sell_trx_id, another colon, and the user buying the card, which we can get from locked_by. So it looks like this:

sm_market_sale:c964035e1ce1f38db695f6c6b1569d0b1c12e286-9:tcpolymath