{"_id":"56326e9ddf556c0d00cd08d7","parentDoc":null,"category":{"_id":"56326e9ddf556c0d00cd08cb","version":"56326e9cdf556c0d00cd08ca","pages":["56326e9ddf556c0d00cd08d5","56326e9ddf556c0d00cd08d6","56326e9ddf556c0d00cd08d7","56326e9ddf556c0d00cd08d8","56326e9ddf556c0d00cd08d9"],"project":"544fc17e698ab40800b4f891","__v":1,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-28T16:17:02.556Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting Started"},"project":"544fc17e698ab40800b4f891","user":"544fc065698ab40800b4f888","__v":4,"version":{"_id":"56326e9cdf556c0d00cd08ca","project":"544fc17e698ab40800b4f891","__v":2,"createdAt":"2015-10-29T19:08:12.724Z","releaseDate":"2015-10-29T19:08:12.724Z","categories":["56326e9ddf556c0d00cd08cb","56326e9ddf556c0d00cd08cc","56326e9ddf556c0d00cd08cd","56326e9ddf556c0d00cd08ce","56326e9ddf556c0d00cd08cf","56326e9ddf556c0d00cd08d0","56326e9ddf556c0d00cd08d1","56326e9ddf556c0d00cd08d2","56326e9ddf556c0d00cd08d3","56326e9ddf556c0d00cd08d4","56d942ac337fd11300d6a251"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"collector","version_clean":"2.1.0","version":"2.1"},"updates":["57453cd9e33ef10e00e1a9e7","589aa87ffce0af0f00acdd2f"],"next":{"pages":[],"description":""},"createdAt":"2015-05-01T09:03:02.632Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"You now have access to all documented API endpoints once you have your [API keys](doc:creating-your-api-keys) ready. All endpoints require authentication, and for the purposes of this example, we are going to use [HMAC](doc:hmac) authentication to [transfer funds](doc:transfers) to an email address.\n\n## 1. Setting up HMAC\n\nHMAC is an authentication method that uses your own account to sign your requests. For the purposes of this tutorial, we'll use the following code snippet to sign our requests:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"\\\"\\\"\\nhmac_example.py\\n\\nSign a request using an API_KEY and an API_SECRET.\\n\\\"\\\"\\\"\\nimport hashlib\\nimport hmac\\nimport time\\nimport json\\n\\nAPI_KEY = 'YOUR_API_KEY'  # Replace this with your API Key\\nAPI_SECRET = 'YOUR_API_SECRET'  # Replace this with your API secret\\n\\n\\ndef get_nonce():\\n    \\\"\\\"\\\"Return a nonce based on the current time.\\n  \\n    A nonce should only use once and should always be increasing.\\n    Using the current time is perfect for this.\\n    \\\"\\\"\\\"\\n    # Get the current unix epoch time, and convert it to milliseconds\\n \\t  return int(time.time() * 1e6)\\n\\n  \\ndef sign_request(url, nonce, body=None):\\n    \\\"\\\"\\\"Return an HMAC signature based on the request.\\\"\\\"\\\"\\n    if body is None:\\n        # GET requests don't have a body, so we'll skip that for signing\\n        message = str(nonce) + url\\n    else:\\n        body = json.dumps(body, separators=(',', ':'))\\n        message = str(nonce) + url + body\\n        \\n    return str(\\n        hmac.new(\\n            str(API_SECRET),\\n            message,\\n            hashlib.sha256\\n        ).hexdigest()\\n    )\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\n\n## 2. Your wallet account\n\nA [transfer](doc:transfers) requires a payload that should specify the [account](doc:crypto-accounts) where the funds should come from, the amount to be sent, and the recipient. The first thing we should do is to retrieve our wallet account details:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\nimport hmac_example\\n\\nurl = 'https://coins.ph/api/v3/crypto-accounts/'\\nnonce = hmac_example.get_nonce()\\nsignature = hmac_example.sign_request(url, nonce)\\n\\nheaders = {\\n    'ACCESS_SIGNATURE': signature,\\n    'ACCESS_KEY': hmac_example.API_KEY,\\n    'ACCESS_NONCE': nonce,\\n    'Content-Type': 'application/json',\\n    'Accept': 'application/json'\\n}\\n\\nrequests.get(url, headers=headers)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThis request would return a response that looks like the one below. What we should take note of is the `id`, which we would use for the next request. An `id` for an [account](doc:crypto-accounts) would never change, which means you could use it for subsequent requests.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n   \\\"crypto-accounts\\\":[\\n      {\\n         \\\"id\\\":\\\"2r45ab4\\\",\\n         \\\"name\\\":\\\"Default Account\\\",\\n         \\\"currency\\\":\\\"BTC\\\",\\n         \\\"balance\\\":\\\"1.5\\\",\\n         \\\"pending_balance\\\":\\\"0.00000000\\\",\\n         \\\"default_address\\\":\\\"1a2a3c4b\\\"\\n      }\\n   ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## 3. Initiating the transfer\n\nNow that we know the `id` of our BTC account, we can now initiate a transfer to `someone:::at:::example.com`. For this example, we would like to give `someone@example.com` 0.5 BTC:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import json\\nimport requests\\nimport hmac_example\\n\\nurl = 'https://coins.ph/api/v3/transfers/'\\nnonce = hmac_example.get_nonce()\\nbody = {\\n    'amount': 0.5,\\n    'account': '2r45ab4',\\n    'target_address': 'someone@example.com'\\n}\\nsignature = hmac_example.sign_request(\\n  url, \\n  nonce, \\n  body=body\\n)\\n\\nheaders = {\\n    'ACCESS_SIGNATURE': signature,\\n    'ACCESS_KEY': hmac_example.API_KEY,\\n    'ACCESS_NONCE': nonce,\\n    'Content-Type': 'application/json',\\n    'Accept': 'application/json'\\n}\\n\\nrequests.post(url, headers=headers, data=body)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nA successful request would return the following response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"transfer\\\": {\\n        \\\"id\\\":\\\"1bbq\\\",\\n        \\\"account\\\":\\\"2r45ab4\\\",\\n        \\\"amount\\\":\\\"0.00010000\\\",\\n        \\\"target_address\\\":\\\"someone@example.com\\\",\\n        \\\"payment\\\": null,\\n        \\\"status\\\":\\\"pending\\\",\\n        \\\"created_at\\\":\\\"2015-05-01T12:11:36.938Z\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nTo learn more about what you can do with the API, you can follow some of our [tutorials](doc:loading-up-a-phone-number).","excerpt":"","slug":"your-first-request","type":"basic","title":"Your first API call"}

Your first API call


You now have access to all documented API endpoints once you have your [API keys](doc:creating-your-api-keys) ready. All endpoints require authentication, and for the purposes of this example, we are going to use [HMAC](doc:hmac) authentication to [transfer funds](doc:transfers) to an email address. ## 1. Setting up HMAC HMAC is an authentication method that uses your own account to sign your requests. For the purposes of this tutorial, we'll use the following code snippet to sign our requests: [block:code] { "codes": [ { "code": "\"\"\"\nhmac_example.py\n\nSign a request using an API_KEY and an API_SECRET.\n\"\"\"\nimport hashlib\nimport hmac\nimport time\nimport json\n\nAPI_KEY = 'YOUR_API_KEY' # Replace this with your API Key\nAPI_SECRET = 'YOUR_API_SECRET' # Replace this with your API secret\n\n\ndef get_nonce():\n \"\"\"Return a nonce based on the current time.\n \n A nonce should only use once and should always be increasing.\n Using the current time is perfect for this.\n \"\"\"\n # Get the current unix epoch time, and convert it to milliseconds\n \t return int(time.time() * 1e6)\n\n \ndef sign_request(url, nonce, body=None):\n \"\"\"Return an HMAC signature based on the request.\"\"\"\n if body is None:\n # GET requests don't have a body, so we'll skip that for signing\n message = str(nonce) + url\n else:\n body = json.dumps(body, separators=(',', ':'))\n message = str(nonce) + url + body\n \n return str(\n hmac.new(\n str(API_SECRET),\n message,\n hashlib.sha256\n ).hexdigest()\n )\n", "language": "python" } ] } [/block] ## 2. Your wallet account A [transfer](doc:transfers) requires a payload that should specify the [account](doc:crypto-accounts) where the funds should come from, the amount to be sent, and the recipient. The first thing we should do is to retrieve our wallet account details: [block:code] { "codes": [ { "code": "import requests\nimport hmac_example\n\nurl = 'https://coins.ph/api/v3/crypto-accounts/'\nnonce = hmac_example.get_nonce()\nsignature = hmac_example.sign_request(url, nonce)\n\nheaders = {\n 'ACCESS_SIGNATURE': signature,\n 'ACCESS_KEY': hmac_example.API_KEY,\n 'ACCESS_NONCE': nonce,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n}\n\nrequests.get(url, headers=headers)", "language": "python" } ] } [/block] This request would return a response that looks like the one below. What we should take note of is the `id`, which we would use for the next request. An `id` for an [account](doc:crypto-accounts) would never change, which means you could use it for subsequent requests. [block:code] { "codes": [ { "code": "{\n \"crypto-accounts\":[\n {\n \"id\":\"2r45ab4\",\n \"name\":\"Default Account\",\n \"currency\":\"BTC\",\n \"balance\":\"1.5\",\n \"pending_balance\":\"0.00000000\",\n \"default_address\":\"1a2a3c4b\"\n }\n ]\n}", "language": "json" } ] } [/block] ## 3. Initiating the transfer Now that we know the `id` of our BTC account, we can now initiate a transfer to `someone@example.com`. For this example, we would like to give `someone@example.com` 0.5 BTC: [block:code] { "codes": [ { "code": "import json\nimport requests\nimport hmac_example\n\nurl = 'https://coins.ph/api/v3/transfers/'\nnonce = hmac_example.get_nonce()\nbody = {\n 'amount': 0.5,\n 'account': '2r45ab4',\n 'target_address': 'someone@example.com'\n}\nsignature = hmac_example.sign_request(\n url, \n nonce, \n body=body\n)\n\nheaders = {\n 'ACCESS_SIGNATURE': signature,\n 'ACCESS_KEY': hmac_example.API_KEY,\n 'ACCESS_NONCE': nonce,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json'\n}\n\nrequests.post(url, headers=headers, data=body)", "language": "python" } ] } [/block] A successful request would return the following response: [block:code] { "codes": [ { "code": "{\n \"transfer\": {\n \"id\":\"1bbq\",\n \"account\":\"2r45ab4\",\n \"amount\":\"0.00010000\",\n \"target_address\":\"someone@example.com\",\n \"payment\": null,\n \"status\":\"pending\",\n \"created_at\":\"2015-05-01T12:11:36.938Z\"\n }\n}", "language": "json" } ] } [/block] To learn more about what you can do with the API, you can follow some of our [tutorials](doc:loading-up-a-phone-number).