Introduction

The Gluwa API follows REST design guideline. The API has predictable resource-oriented URL's and returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

We support a separate environment for testing purposes. When testing, use the sandbox credentials and URL. When you are ready to go live, use the live credentials and URL.

Base URL
https://api.gluwa.com

Base URL
https://sandbox.api.gluwa.com

Authentication

HTTPS

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without proper authentication will also fail.

Signature

Signature is used to verify the ownership of a cryptocurrency (e.g., Bitcoin or Ethereum) wallet. A cryptocurrency wallet is a set of a private key and a public key. You can verify the ownership of a cryptocurrency wallet by encrypting an arbitrary message with its private key. Anyone who has the public key can decrypt the encryption with it and get the original text.

Gluwacoin Signature

To verify the ownership of a Gluwacoin wallet, you need to create an Ethereum signature. This is because Gluwacoins are ERC-20 tokens. If you create a signature of the transfer information, Gluwacoin smart contract can use it as a proof-of-intention.

Think of signature as a signed contract. You send the contract to Gluwa to submit it for you. The authority (Gluwacoin smart contract in this case) can verify that the information in the contract is genuine with your signature.

You can create the signature using official Ethereum Web3 library, web3.js or web3.py, or its unofficial implementation in other languages.

web3.js example
var Web3 = require('web3');
​
var web3 = new Web3(Web3.givenProvider);
​
// you will get the value below if you are successful
// '0x43a26051362b8040b289abe93334a5e3662751aa691185ae9e9a2e1e0c169350'
const messageHash = web3.utils.soliditySha3({t: 'string', v: "Some data"});
​
// example private key
const privateKey = '0x69965ac017a7d34820a029c6c815d81271d2b41878b85802975aa75a809c2e09';
​
const sign = web3.eth.accounts.sign(messageHash, privateKey);
​
const signature = sign.signature;
​
// you will get the value below if you are successful
// 0xc3d08236a76af3a25765a20de27edbc102197899482de8693118b7ffac95210005dc69be61e2838a4df72fe3fa76895cc3abb4c8957f8c000d6c4e1292c475ad1b
console.log(signature);

ethers.js example
var ethers = require('ethers');
​
const messageHash = ethers.utils.solidityKeccak256(
    [ 'string' ], // types
    [ 'Some data' ] // values
);
​
const messageHashBinary = ethers.utils.arrayify(messageHash);
​
// example private key
const privateKey = '0x69965ac017a7d34820a029c6c815d81271d2b41878b85802975aa75a809c2e09'
​
let wallet = new ethers.Wallet(privateKey);
​
// creates a Promise with the Signature
let signPromise = wallet.signMessage(messageHashBinary);
​
// you will get the value below if you are successful
// 0xc3d08236a76af3a25765a20de27edbc102197899482de8693118b7ffac95210005dc69be61e2838a4df72fe3fa76895cc3abb4c8957f8c000d6c4e1292c475ad1b
signPromise.then(function (signature) {
    console.log(signature)
});

X-REQUEST-SIGNATURE

The Gluwa API uses X-REQUEST-SIGNATURE to authenticate transaction requests.

• A signed message from the user using the private key.

• The message is unix timestamp. You compare the unixtimestamp in the header string and the unix timestamp from the decrypted signature and compare.

• We use the public key to decrypt the signature and verify that the address actually belongs to the requester.

• The timestamp is used to check expiry of the signature. Expiry is 10 minutes.

• If this validation fails, you will get a 403 response.

Creating X-REQUEST-SIGNATURE

X-REQUEST-SIGNATURE is a base64 encoded string of {unixtimestamp}.{signature}

1. Get the current unix time stamp in seconds, unixtimestamp.

2. Using unixtimestampas a message, create a signature. Refer to the Signature section above for details.

3. Concatenate unixtimestamp and signature separated with .. For example, if the unixtimestamp was "12345" and the signature was "asdf", you will get 12345.asdf.

4. Base64 encoded the string you got from above to get X-REQUEST-SIGNATURE. You should get MTIzNDUuYXNkZg==.

API Keys

The Gluwa API uses API keys to authenticate some types of requests. You can view and manage your API keys in the Gluwa Dashboard.

The API key and secret will be passed to us using the following way:

• API Key Authorization Code: base64 encoded string of {api key}:{api secret}

• We use HTTP Basic Auth to use API Key authentication. Provide your API key as a header. -H "Authorization: Basic {Base64 Encoded API Keys}".

Authenticated Request
$ curl https://api.gluwa.com/V1/QRCode \
  -H "Authorization: Basic {BASE64ENCODEDAPIKEY}"

Code Examples

// example key and secret
var key = 'abcd';
var secret = '1234';
var data = key + ':' + secret;
​
var encodedBytes = Buffer.from(data);
​
// this is Base64 Encoded API Keys
var encodedString = encodedBytes.toString('base64');
​
// you should get 'YWJjZDoxMjM0' from the example values
console.log(encodedString)

import base64
​
# example key and secret
key = 'abcd'
secret = '1234'
​
data = '%s:%s' % (key, secret)
​
encodedBytes = base64.b64encode(data.encode('utf-8'))
​
 # this is Base64 Encoded API Keys
encodedString = encodedBytes.decode('utf-8')
​
# you should get 'YWJjZDoxMjM0' from the example values
print(encodedString)

Core Resources

Balance

This is an object representing the Bitcoin or Gluwacoin balance of a certain address. You can retrieve it to see the current balance on your Gluwa account.

You can also retrieve the nonce, which is used to sign the Ethereum contract.

The Balance Object

{
	"Balance": "100000",
	"Currency": "USDG",
	"Nonce": 0
}

​

​

​

Fee

To learn the recommended fee amount for a transaction, you can retrieve a Fee object. A blockchain charges transaction fees for processing transaction (e.g., Bitcoin transaction fee). Though transaction fees are optional, a transaction with higher fee gets processed first. Fee object includes the recommended minimum transaction fee, which is expected to get your transaction processed under a reasonable amount of time.

Fee Object

{
    "Currency": "USDG",
    "MinimumFee": "0.5000"
}a

​

​

​

Transaction

To transfer funds to another user, you can create a Transaction object. You can retrieve an individual transaction as well as list all transactions. Transactions are identified by a unique, random TxnHash.

Transaction Object

Transaction Status

[
	{
		"Status": "Unconfirmed",
		"Amount": "1.00",
		"Fee": "0.50",
		"Currency": "USDG",
		"Source": string[],
		"Target": string[],
		"TxnHash": string,
		"CreatedDateTime": DateTime,
		"ModifiedDateTime": DateTime,
		"MerchantOrderID": string?,
		"Note": string?
	},
	{
		"Status": "Unconfirmed",
		"Amount": "1.00",
		"Fee": "0.50",
		"Currency": "USDG",
		"Source": string[],
		"Target": string[],
		"TxnHash": string,
		"CreatedDateTime": DateTime,
		"ModifiedDateTime": DateTime,
		"MerchantOrderID": string?,
		"Note": string?
	}
]

​

​

​

​

{
	Status: Unconfirmed, Confirmed, Failed
	Amount: string (negative if taken away from the source)
	Fee: string (gas fee + service fee)
	Currency: BTC, USDG, KRWG
	Source: string[]
	Target: string[]
	TxnHash: string
	CreatedDateTime: DateTime
	ModifiedDateTime: DateTime
	MerchantOrderID: string?
	Note: string?
}

​

​

​

​

{}
​

​

​

​

​

ETHless Transfer

Gluwacoin is an ERC-20 token. A user can transfer Gluwacoin as he or she would transfer any other ERC-20 token, but the user will need to spend Ether to do so. Gluwa allows its users to move Gluwacoin without Ether by paying the transaction fee in Gluwacoin to Gluwa instead. We call this ETHless transfer.

How to Create a Signature for Create Transaction Endpoint

Creating Signature for Create Transaction
var ethers = require('ethers');
​
// create an array of message values
const messageValues = [
    '{Contract Address}',// choose the contract of the token you are using
    '{Source}',
    '{Target}',
    // Note that Amount and Fee is in uint256, not int.
    // You can convert int to uint256 by multiplying the int value with 10^18.
    ethers.utils.parseEther({Amount in uint256}).toString(),// Ethereum uses uint256
    ethers.utils.parseEther({Fee in uint256}).toString(),// Ethereum uses uint256
    String({Nonce}),
];
​
const messageHash = ethers.utils.solidityKeccak256(
    [ 'address', 'address', 'address', 'uint256', 'uint256', 'uint256' ],
    messageValues
);
​
const messageHashBinary = ethers.utils.arrayify(messageHash);
​
let wallet = new ethers.Wallet('{Sender\'s private key}');
​
// creates a Promise with the Signature
let signPromise = wallet.signMessage(messageHashBinary);

Gluwacoin Contracts

• USD Gluwacoin - 0xfb0aaa0432112779d9ac483d9d5e3961ece18eec​

• KRW Gluwacoin - 0x4cc8486f2f3dce2d3b5e27057cf565e16906d12d​

QR Code

Instead of typing a long address, a user may scan QR code to initiate a transfer on Gluwa mobile application.

Types of QR Code

Gluwa has two types of QR code:

• Transfer QR Code: A user can generate Transfer QR code using Gluwa mobile application. If you scan the QR code using Gluwa mobile application, you initiate a transfer to the user. This QR code initiates an exact amount transfer. So you see the fee information on the transaction summary page.

• Payment QR Code: A user can generate Payment QR code using Gluwa API. The user needs to obtain API keys to do this. This QR code forces the receiver to pay the fee. This means that Gluwa mobile application does not show the fee information on the transaction summary page.

​

​

​

​

​

How to Create a Signature for Create Payment QR Code Endpoint

Learn how to create the Signature from the Body Parameters from the example below.

var ethers = require('ethers');
​
// example private key
let key = '6af4b282a849d9e6fee02d63867285c3de1167ac445d6807e673d3c3749414b7';
let wallet = new ethers.Wallet(key);
​
// example timestamp
let timestamp = '1568414920';
// example code to get Unix timestamp
// let timestamp = Math.round((new Date()).getTime() / 1000).toString();
​
// creates a Promise with the Signature
let signPromise = wallet.signMessage(timestamp);
​
signPromise.then((signedTransaction) => {
    // you should get below from the example values
    // 0xf5ccf41438561cc58d4efba9d944a01f8e7f27258091280154a8c48fea14521c3027e47e10d87328c873304975b8c30d152a50a313f2e22b470f59f49df08dde1c
    console.log(signedTransaction);
    
    var data = timestamp + '.' + signedTransaction;
    
    var encodedBytes = Buffer.from(data);
​
    // this is Base64 Encoded API Keys
    var encodedString = encodedBytes.toString('base64');
​
    // you should get below from the example values
    // MTU2ODQxNDkyMC4weGY1Y2NmNDE0Mzg1NjFjYzU4ZDRlZmJhOWQ5NDRhMDFmOGU3ZjI3MjU4MDkxMjgwMTU0YThjNDhmZWExNDUyMWMzMDI3ZTQ3ZTEwZDg3MzI4Yzg3MzMwNDk3NWI4YzMwZDE1MmE1MGEzMTNmMmUyMmI0NzBmNTlmNDlkZjA4ZGRlMWM=
    console.log(encodedString);
});

​