beta

Visit $MUSIC Forum
The Musicoin API provides 3rd party developers with the opportunity to integrate with the Musicoin platform. This pages documents the available APIs, but please note the API is currently considered beta software, and is subject to change.

Authentication

Each request must include a clientId and clientSecret in the header. You can obtain a clientId and clientSecret when you create an application account. Additionally, in order to allow your users to stream music, you will need a non-zero balance in your application account.

Creating an account

Currently, client application accounts are available by invite only. To request an invite, email musicoin@musicoin.org.

Working with files

Musicoin uses a distributed file system called IPFS. Images and audio posted to Musicoin do not reside on the Musicoin servers. Instead, the are distributed on IPFS. This means the client applications will need to have their own instance of IPFS running on a server that can proxy the files for them.

When a resource is located in ipfs, the resource URL will be formatted as follows:

  • ipfs://HASH: This indicates that the file is stored in ipfs under the given hash and is not encrypted.
  • eipfs://HASH: This indicates that an encrypted version of the file is stored in ipfs under the given hash. A key is required to decrypt the file. Currently, this applies only to audio files. See the /license/ppp api for details on obtaining a key to decrypt the file.
// TODO: Provide minimal Node.js application to proxy IPFS files


Artist

GET /artist/profile/:address

Returns details about the artist at the given address

  request({
    url: "http://api.musicoin.org/artist/profile/0x4c54039e4480031f69226e2ec19454b239230870",
    qs: {},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, artist) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process artist
  });
            

output

{
  "descriptionUrl": "ipfs://QmQsvpGLQc9zV1tBVeri6HBturkmLmPjTQkiBxjxFE4fsX",
  "artistName": "Dan",
  "owner": "0xe5233d15f4993c83f066575accde2ce10e369188",
  "imageUrl": "ipfs://QmUs9Z5rT1E9aVKtzHY9FdyuXVPKivhz5UFnuLa1Yh5W2o",
  "followers": "0",
  "socialUrl": "ipfs://QmdUm1rHLYVy95PJCfrsQmf2Xc63URFH72Ez3pwz3uJ25D",
  "tipTotal": "0",
  "tipCount": "0",
  "balance": "540"
}
            


License

GET /license/detail/:address

Returns details about the license contract at the given address

  request({
    url: "http://api.musicoin.org/license/detail/0x1a186183da9eecefda624e947143f3c9d7dc9e6a",
    qs: {},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, license) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process license
  });
            

output

{
  "resourceUrl": "eipfs://Qmc1U5u6gzuzzhw6wHw92LNTvnoEEesqeUnWZ6Cu2RP1sh",
  "createdBy": "0xe5233d15f4993c83f066575accde2ce10e369188",
  "totalShares": "1",
  "title": "Test",
  "getContributorsLength": "1",
  "licenseVersion": "1",
  "metadataVersion": "0",
  "artistProfileAddress": "0x4c54039e4480031f69226e2ec19454b239230870",
  "totalEarned": "94000000000000000000",
  "owner": "0xe5233d15f4993c83f066575accde2ce10e369188",
  "playCount": "94",
  "contractVersion": "v0.5",
  "imageUrl": "ipfs://QmT97fbFQcjacL3jCvY53MrU6hDBhyW4VjzQqSEoUcEPez",
  "weiPerPlay": "1000000000000000000",
  "totalTipped": "0",
  "metadataUrl": "ipfs://QmbJWAESqCsf4RFCqEY7jecCashj8usXiyDNfKtZCwwzGb",
  "getRoyaltiesLength": "0",
  "tipCount": "0",
  "balance": "0",
  "contributors": [
    {
      "address": "0x4c54039e4480031f69226e2ec19454b239230870",
      "shares": "1"
    }
  ],
  "royalties": [],
  "coinsPerPlay": "1",
  "address": "0x1a186183da9eecefda624e947143f3c9d7dc9e6a"
}
            

GET /license/ppp/:address

Initiates a Pay-per-play transaction, deducting the price of the license from the account associated with the clientId. Returns the key needed to decrypt the audio file associated with the license at the given address. Typically, a 3rd party backend server would request the key using this API and then use it to decrypt a stream from IPFS, piping the decrypted stream back to their client.

  request({
    url: "http://api.musicoin.org/license/ppp/0x1a186183da9eecefda624e947143f3c9d7dc9e6a",
    qs: {},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, keyResult) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process keyResult
  });
            

output

{
  "key": "XYZ12345"
}
            


Transactions

GET /tx/detail/:hash

Returns processed details about the transaction with the given hash. This is useful if you want to know what the transaction was at a higher level (e.g play, tip, contract creation)

  request({
    url: "http://api.musicoin.org/tx/detail/0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
    qs: {},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, txDetails) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process txDetails
  });
            

output

{
  "transactionHash": "0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
  "txType": "function",
  "from": "0xb560530ea7939a88093123af648f718f15e540cc",
  "to": "0xf751fd1140173550daaadcaaf64b3a6db6d9c4e6",
  "eventType": "play",
  "licenseAddress": "0xf751fd1140173550daaadcaaf64b3a6db6d9c4e6",
  "title": "Our Times",
  "balance": "0"
}
            

GET /tx/raw/:hash

Returns raw details about the transaction with the given hash (directly from blockchain)

  request({
    url: "http://api.musicoin.org/tx/raw/0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
    qs: {},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, txRawDetails) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process txRawDetails
  });
            

output

{
  "blockHash": "0xeb525bee5f5f03d98483fa0fcc664792863d35709d6cdc8e9bb432660b8b09ab",
  "blockNumber": 119291,
  "from": "0xb560530ea7939a88093123af648f718f15e540cc",
  "gas": 940000,
  "gasPrice": "20000000000",
  "hash": "0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
  "input": "0x93e84cd9",
  "nonce": 227,
  "to": "0xf751fd1140173550daaadcaaf64b3a6db6d9c4e6",
  "transactionIndex": 1,
  "value": "1000000000000000000"
}
            

GET /tx/status/:hash

Returns the status of a transaction (complete, pending, error, unknown). For complete transactions, the transaction receipt will be included.

  request({
    url: "http://api.musicoin.org/tx/status/0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
    qs: {},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, txRawDetails) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process txRawDetails
  });
            

output

{
  "status": "complete",
  "receipt": {
    "blockHash": "0xeb525bee5f5f03d98483fa0fcc664792863d35709d6cdc8e9bb432660b8b09ab",
    "blockNumber": 119291,
    "contractAddress": null,
    "cumulativeGasUsed": 72597,
    "from": "0xb560530ea7939a88093123af648f718f15e540cc",
    "gasUsed": 51597,
    "logs": [
      {
        "address": "0xf751fd1140173550daaadcaaf64b3a6db6d9c4e6",
        "blockHash": "0xeb525bee5f5f03d98483fa0fcc664792863d35709d6cdc8e9bb432660b8b09ab",
        "blockNumber": 119291,
        "data": "0x000000000000000000000000000000000000000000000000000000000000002c",
        "logIndex": 0,
        "topics": [
          "0x1a89c1c30743c234698485f5369000475c99a479a87f18ff17e5b581e6fdecdd"
        ],
        "transactionHash": "0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
        "transactionIndex": 1
      }
    ],
    "root": "a6275086c77efe7ad8555ad355442936802ef31c1294e64959bedabd7a8100ea",
    "to": "0xf751fd1140173550daaadcaaf64b3a6db6d9c4e6",
    "transactionHash": "0xb20be759701a6649307f5376bdb9a90daaa01fb6336f1a205a2760562b4b4d14",
    "transactionIndex": 1
  }
}
            

GET /tx/history/:address?length=:length&start=:start

Returns transaction history for the given address

  request({
    url: "http://api.musicoin.org/tx/history/0x4c54039e4480031f69226e2ec19454b239230870",
    qs: {"length":2,"start":4},
    json: true,
    headers: {
      clientID: YOUR_CLIENT_ID,
      clientSecret: YOUR_CLIENT_SECRET
    }
  }, function(error, response, history) {
    if (error) {
      console.log(`Request failed with ${error}`);
    }
    // process history
  });
            

output

[
  {
    "transactionHash": "0x1e2c2a23884e2417a8d4f2aa46e58254381614390289cec10806c706f53dbac3",
    "txType": "function",
    "from": "0xe5233d15f4993c83f066575accde2ce10e369188",
    "to": "0xb7eb7fb1b8ba9a3c26c675dba646ef3574f87a32",
    "eventType": "play",
    "licenseAddress": "0xb7eb7fb1b8ba9a3c26c675dba646ef3574f87a32",
    "title": "Some Song",
    "balance": "0",
    "blockNumber": 112655,
    "internal": {
      "from": "0xb7eb7fb1b8ba9a3c26c675dba646ef3574f87a32",
      "to": "0x4c54039e4480031f69226e2ec19454b239230870"
    },
    "musicoins": "1",
    "timestamp": 1484042659
  },
  {
    "transactionHash": "0xe0c7a955cd9b608233ca46f813a5e993f2ff12bb7da9728ed1320c510092bca0",
    "txType": "function",
    "from": "0xe5233d15f4993c83f066575accde2ce10e369188",
    "to": "0x1e893581aabad9c8a79659a7160180830fed1f7a",
    "eventType": "play",
    "licenseAddress": "0x1e893581aabad9c8a79659a7160180830fed1f7a",
    "title": "Another Song",
    "balance": "0",
    "blockNumber": 112655,
    "internal": {
      "from": "0x1e893581aabad9c8a79659a7160180830fed1f7a",
      "to": "0x4c54039e4480031f69226e2ec19454b239230870"
    },
    "musicoins": "1",
    "timestamp": 1484042659
  }
]
            
Connect with us
Designed by the Musicoin project, © 2017
Site best viewed with Chrome on macOS