Getting started with The Ocean API for Node.js
Ari from The Ocean X here. This month we unveiled our public API for The Ocean, the most efficient and accessible ERC20 exchange that’s coming out this year. For all you eager developers out there, here’s a step-by-step guide on how to make your first trade on our platform via the Kovan test network using our npm package.
There’s no real money involved, and we’ll be assuming you have some familiarity with Ethereum and Node.js. Don’t fret if you get stuck though! Now’s the prime time to experiment, learn about decentralized exchanges, and ask us questions on our dedicated Telegram channel.
What you’ll need
Parity
Parity is a multi-functional Ethereum client that let’s you manage your wallet and interact with the blockchain. There are several ways to install it, but I prefer Homebrew. You can find instructions here (or download the installers here).
Run this command to open it up on Kovan.
parity ui --testnetThe ui bit will pop up a browser window with the client dashboard, so sit back for a couple minutes while Parity syncs up to the test network.
An address on Kovan Testnet
If this is your first time starting Parity, you’ll be walked through creating an Ethereum account with a password and a recovery phrase. You can use the created address to trade on The Ocean, or you can import an existing private key.
Plug this address into Metamask, a nifty browser extension that allows you run dApps without running the full Ethereum node. If you’re new to Metamask, you can start here. Otherwise, double-check that Metamask is set to run on Kovan Test Net, and from there, you can use the 0x portal to mint, wrap, and allow tokens.
Some Ether
In order to do most things on the blockchain, you need a small amount of Ether. There are a several faucets that distribute it, but the easiest method is to click the “Request” button on the 0x portal.
Go ahead and click it whole bunch of times. It’s free!
Some Tokens
For this step, you need the address that you want to trade with imported into Metamask (which, once again, should be running on the Kovan test network).
First, add the tokens to the list in the 0x portal by clicking the “+” button.
Then, choose any token and add as many as you want. Once they’re in the list, you’ll just have to click “Mint” and a Metamask window will appear asking you to sign the transaction. Confirm with “Submit” and the test tokens will be sent to your account without any cost to you.
Token Allowances
Before you leave the token page, make sure to toggle all the Allowance switches to green. Each one will require you to sign with Metamask. This step allows the 0x contract to move your tokens only when you’ve signed the order during a trade. Thus, no need to worry about them being stolen.
If you’re interested in how this works, you should read the incredibly well-written 0x white paper and even look at the code for the 0x exchange contract.
Wrapped Ether
Finally, if you want to trade Ether for a token, you can wrap it in the “Wrap ETH” section of 0x portal. Just click on the “Wrap” button.
And sign the Metamask transaction when it pops up. Be careful not to wrap ALL your Ether, as you will need some small amount to pay the gas on future transactions. You can unwrap the Ether at any time using the same interface. If you’re curious what WETH is, you can find out here.
The Ocean API Key and Secret
To get API access, go sign up to beta.theoceanx.com and follow the steps provided there. Make sure to keep your keys safe.
Setting up a project
To set up a Node.js project, create a directory and run npm init from inside of it.
Then to install the-ocean-x client library, run
npm install --save the-oceanand add some babel packages to use ES2015
npm install --save-dev babel-core babel-preset-es2015 babel-watchand add the following line to your scripts object in package.json
"start": "babel-watch index.js --presets es2015",You’ll need to provide the client with some info when you initialize. Create a file called index.js and add the following code. Be sure to replace your API key and secret with the ones you obtained from beta.theoceanx.com above.
import createOcean from 'the-ocean'
import Web3 from 'web3'(async () => {
const provider = new Web3.providers.HttpProvider('http://localhost:8545')
let ocean = await createOcean({
api: {
key: '<my the ocean x api key>',
secret: '<my the ocean x api secret>',
baseURL: 'https://kovan.theoceanx.com/api/v0'
},
web3Provider: provider
})const pairs = await ocean.marketData.tokenPairs()
const myPair = pairs[0]console.log('Trading on pair : ', myPair.baseToken.symbol + '/' + myPair.quoteToken.symbol)
const data = {
baseTokenAddress: myPair.baseToken.address,
quoteTokenAddress: myPair.quoteToken.address,
side: 'buy',
orderAmount: '180000000000000000',
feeOption: 'feeInNative'
}
console.log('Market order result :' , await ocean.trade.newMarketOrder(data))
})()
This code will execute a buy market order on the first available pair. But before you can run it, you’ll need to have Parity running and unlocked.
Running Parity with unlocked account
To run Parity with an account unlocked, you’ll have to stop the instance that you have running and restart it. Put you password in a local file (here I used ~/secret.txt)and run the following command.
parity --testnet --unlock “0xabc123myEthereumAddressToTradeWith” --password ~/secret.txtThis will run Parity listening on port 8545. It’s your responsibility to keep your Parity password secret and you should use whatever precautions are appropriate for your particular situation. Now that Parity is running, you should be able to make your first trade by simply running npm start
You’re done!
And that’s it. You’re now an algorithmic trading bot developer on a decentralized cryptoasset exchange! Now’s probably a good time to check out our extensive documentation and learn about all the other functionality that’s available through our client library.
__________________________
Having some trouble or just have a quick question? Join our exclusive Telegram group. We’d be happy to give you a hand.
