< Back

Private endpoints

**NOTE** This API specification is still under heavy development. Follow CryptFolio Updates to stay in the loop.

There are two ways to access your private data: through OAuth2, or through API key.

Using OAuth2

With all of these endpoints you will need to get permission from the user to access this data. CryptFolio uses the common OAuth2 standard to implement authorisation and authentication.

  1. Make sure that you have signed up for a CryptFolio account.
  2. In your profile, visit your registered applications
  3. Create a new application, and list all of your valid redirection URIs.
  4. You will be given an application key and secret. Use these to initialise your OAuth2 client.

See some example OAuth2 authentication code.

Using API keys

For read-only endpoints, you can also create API keys for your own account, and use the API key as a parameter, rather than going through OAuth2 setup.

You can provide the API key with the GET parameter api_key=..., or by setting the request header X-API-KEY: ... (recommended).

API keys can only be set up with read and/or info scopes.

Scopes

Endpoints require the following scopes:

If the user has not provided your application with sufficient scope your request will fail with 403 Forbidden.

User information

GET /api/user latest

Retrieve key information about this user. Requires one of the admin, read or info scopes.

GET /api/user

{
  "success": true,
  "time": 1512697998,
  "result": {
    "name": "Test user",
    "email": "test@openclerk.org",
    "created_at": "2017-11-06T04:54:54+00:00"
  }
}

Portfolios

GET /api/portfolios latest

List all of your portfolios.

GET /api/portfolios

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "id": 1,
    "title": "My portfolio",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances_last_updated": "2017-11-23T23:01:44+00:00",
    "histories_last_updated": "2017-11-23T23:01:44+00:00",
    "converted_balances_last_updated": "2017-11-23T23:01:44+00:00",
    "converted_histories_last_updated": "2017-11-23T23:01:44+00:00",

    "currencies": 3,
    "accounts": 4,
    "addresses": 5,
    "offsets": 0
  }, {
    ...
  }]
}

GET /api/portfolios/ID latest

List the properties and accounts of a portfolio.

GET /api/portfolios/1

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 1,
    "title": "My portfolio",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances_last_updated": "2017-11-23T23:01:44+00:00",
    "histories_last_updated": "2017-11-23T23:01:44+00:00",
    "converted_balances_last_updated": "2017-11-23T23:01:44+00:00",
    "converted_histories_last_updated": "2017-11-23T23:01:44+00:00",

    "currencies": [...],
    "accounts": [...],
    "addresses": [...],
    "offsets": [...],
    "source": "private-api"
  }
}

POST /api/portfolios latest

Create a new portfolio.

POST /api/portfolios

{"title":"My portfolio","currencies":["btc","usd"]}

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 1,
    "title": "My portfolio",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances_last_updated": null,
    "histories_last_updated": null,
    "converted_balances_last_updated": null,
    "converted_histories_last_updated": null,

    "currencies": [{
      "title": "Bitcoin", "code": "btc"
    }, {
      "title": "United States dollar", "code": "usd"
    }],
    "accounts": [],
    "addresses": [],
    "offsets": [],
    "source": "private-api"
  }
}

PATCH /api/portfolios/ID latest

Update the attributes or currencies of a portfolio.

PATCH /api/portfolios/1

{"title":"My updated portfolio"}

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 1,
    "title": "My updated portfolio",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances_last_updated": null,
    "histories_last_updated": null,
    "converted_balances_last_updated": null,
    "converted_histories_last_updated": null,

    "currencies": [{
      "title": "Bitcoin", "code": "btc"
    }, {
      "title": "United States dollar", "code": "usd"
    }],
    "accounts": [],
    "addresses": [],
    "offsets": [],
    "source": "private-api"
  }
}

DELETE /api/portfolios/ID latest

Delete a portfolio.

DELETE /api/portfolios/1

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 1,
    "title": "My portfolio",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances_last_updated": null,
    "histories_last_updated": null,
    "converted_balances_last_updated": null,
    "converted_histories_last_updated": null,

    "currencies": [{
      "title": "Bitcoin", "code": "btc"
    }, {
      "title": "United States dollar", "code": "usd"
    }],
    "accounts": [],
    "addresses": [],
    "offsets": [],
    "source": "private-api"
  }
}

GET /api/portfolios/ID/balances latest async

Get all current balances for a portfolio (the current balances of all accounts, addresses and offsets, summed together).

GET /api/portfolios/1/balances

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "currency": "btc",
    "balance": "10.0",
    "balance_at": "2017-11-06T04:54:54+00:00",
    "source": "cryptfolio"
  }, {
    "currency": "usd",
    "balance": "0.0",
    "balance_at": "2017-11-06T04:54:54+00:00",
    "source": "cryptfolio"
  }]
}

GET /api/portfolios/ID/balances/currency coming soon

GET /api/portfolios/ID/balances/history coming soon

Get the historical balances for a portfolio.

GET /api/portfolios/ID/balances/currency/history coming soon

Get the historical balances for a portfolio for a particular currency.

GET /api/portfolios/ID/converted latest async

Get the converted balances for a portfolio, in each of the users’ portfolio currencies, as if all balances across all currencies were converted into that currency.

GET /api/portfolios/1/converted

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "currency": "btc",
    "balance": "10.0",
    "balance_at": "2017-11-06T04:54:54+00:00",
    "source": "cryptfolio"
  }, {
    "currency": "usd",
    "balance": "117753.60",         # e.g. BTC/USD is 11,775.36
    "balance_at": "2017-11-06T04:54:54+00:00",
    "source": "cryptfolio"
  }]
}

GET /api/portfolios/ID/converted/history coming soon

Get the historical converted balances for a portfolio.

GET /api/portfolios/ID/inventory latest async

List all of the inventory balances for a portfolio, in each of the users’ portfolio currencies. A transaction is included in the inventory if the transaction type is of type purchase or sale (learn more).

GET /api/portfolios/1/inventory

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "currency": "btc",
    "balance": "0.5",    # May be different to /balances for txns that are not categorised
    "balance_at": "2017-11-06T04:54:54+00:00",
    "source": "cryptfolio"
  }, {
    "currency": "usd",
    "balance": "0.0",
    "balance_at": "2017-11-06T04:54:54+00:00",
    "source": "cryptfolio"
  }]
}

Addresses

GET /api/portfolios/ID/addresses latest

List the addresses on a portfolio. This will list the public address hashes for each address.

GET /api/portfolios/1/addresses

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "id": 1,
    "title": "My address",
    "address": "1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu",
    "currency": { "title": "Bitcoin", "code": "btc" }
  }, {
    ...
  }]
}

GET /api/portfolios/ID/addresses/ID latest

Get the full details of an address.

GET /api/portfolios/1/addresses/1

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 1,
    "title": "My address",
    "address": "1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu",
    "currency": { "title": "Bitcoin", "code": "btc" },
    "valid": true,

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",
    "txns_last_updated": "2017-11-23T23:01:44+00:00",
    "source": "private-api"
  }
}

GET /api/portfolios/ID/addresses/ID/balances latest async

Get the balances for a particular address.

GET /api/portfolios/1/addresses/1/balances

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "currency": { "title": "Bitcoin", "code": "btc" },
    "balance": "50.00501",
    "transactions": 3,           # may be null

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "source": "blocktrail"
  }]
}

GET /api/portfolios/ID/addresses/ID/transactions latest async

Get the transactions for a particular address.

GET /api/portfolios/1/addresses/1/transactions

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "currency": { "title": "Bitcoin", "code": "btc" },
    "delta": "50.0",             # positive (incoming) or negative (outgoing)
    "txn_at": "2017-11-06T04:54:54+00:00",
    "fee": "0.0",                # any fee associated with the txn, may be null
    "reference": "abc123",       # any reference associated with the txn, may be null;
                                 # for addresses, this is often the network transaction ID

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "source": "blocktrail"
  }, {
    ...
  }]
}

POST /api/portfolios/ID/addresses latest

Create a new portfolio address.

POST /api/portfolios/1/addresses

{"title":"New address","address":"1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu","currency":"btc"}

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 2,
    "title": "New address",
    "address": "1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu",
    "currency": { "title": "Bitcoin", "code": "btc" },
    "valid": true,

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",
    "txns_last_updated": null,
    "source": "private-api"
  }
}

PATCH /api/portfolios/ID/addresses/ID latest

Update an existing address with a title or address.

PATCH /api/portfolios/1/addresses/2

{"title":"A new address title"}

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 2,
    "title": "A new address title",
    "address": "1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu",
    "currency": { "title": "Bitcoin", "code": "btc" },
    "valid": true,

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",
    "txns_last_updated": null,
    "source": "private-api"
  }
}

DELETE /api/portfolios/ID/addresses latest

Delete a portfolio address.

DELETE /api/portfolios/1/addresses/2

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 2,
    "title": "A new address title",
    "address": "1JfbZRwdDHKZmuiZgYArJZhcuuzuw2HuMu",
    "currency": { "title": "Bitcoin", "code": "btc" },
    "valid": true,

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",
    "txns_last_updated": null,
    "source": "private-api"
  }
}

Accounts

GET /api/portfolios/ID/accounts coming soon

List the accounts on a portfolio. This list will not reveal keys or secrets.

GET /api/portfolios/1/accounts

{
  "success": true,
  "time": 1512697998,
  "result": [{
  "accounts": [{
    "id": 1,
    "title": "My account",
    "wallet": { "title": "Bittrex", "code": "bittrex" },
    "valid": true,

    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",
    "last_updated": "2017-11-23T23:01:44+00:00",
    "txns_last_updated": "2017-11-23T23:01:44+00:00",
    "history_last_updated": "2017-11-23T23:01:44+00:00"
  }, {
    ...
  }]
}

GET /api/portfolios/ID/accounts/ID/balances coming soon

GET /api/portfolios/ID/accounts/ID/txns coming soon

GET /api/portfolios/ID/accounts/ID/history coming soon

POST /api/portfolios/ID/accounts coming soon

DELETE /api/portfolios/ID/accounts coming soon

Offsets

GET /api/portfolios/ID/offsets latest/span>

List the offsets on a portfolio.

GET /api/portfolios/1/offsets

{
  "success": true,
  "time": 1512697998,
  "result": [{
    "id": 1,
    "title": "My offset",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00"
  }, {
    ...
  }]
}

GET /api/portfolios/ID/offsets/ID latest

Get the full details of an offset, including its balances.

GET /api/portfolios/1/offsets/1

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 1,
    "title": "My offset",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances": [{
      "currency": "btc",
      "balance": "10.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }, {
      "currency": "ltc",
      "balance": "1.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }]
  }
}

POST /api/portfolios/ID/offsets latest

Create a new offset with a collection of offset balances.

POST /api/portfolios/1/offsets

{"title":"My second offset","balances":[
  {"currency":"btc","balance":"10"},
  {"currency":"ltc","balance":"1"}
]}

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 2,
    "title": "My second offset",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances": [{
      "currency": "btc",
      "balance": "10.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }, {
      "currency": "ltc",
      "balance": "1.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }]
  }
}

PATCH /api/portfolios/ID/offsets/ID latest

Update an existing offset with a new title. If balances is set, replaces the offset balances with a new collection of balances.

PATCH /api/portfolios/1/offsets/2

{"title":"My second offset","balances":[
  {"currency":"btc","balance":"5"},
  {"currency":"usd","balance":"10"}
]}

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 2,
    "title": "My second offset",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances": [{
      "currency": "btc",
      "balance": "5.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }, {
      "currency": "usd",
      "balance": "10.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }]
  }
}

DELETE /api/portfolios/ID/offsets latest

Delete a portfolio offset and its associated balances.

DELETE /api/portfolios/1/offsets/2

{
  "success": true,
  "time": 1512697998,
  "result": {
    "id": 2,
    "title": "My second offset",
    "created_at": "2017-11-06T04:54:54+00:00",
    "updated_at": "2017-11-23T23:01:44+00:00",

    "balances": [{
      "currency": "btc",
      "balance": "5.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }, {
      "currency": "usd",
      "balance": "10.0",
      "created_at": "2017-11-06T04:54:54+00:00",
      "updated_at": "2017-11-23T23:01:44+00:00",
      "source": "private-api"
    }]
  }
}

Example flow: Getting the history of an address

  1. POST /api/portfolios/1/addresses to create a new address with an id of 12
  2. GET /api/portfolios/1/addresses/12/balances to get the latest address balance
  3. GET /api/portfolios/1/addresses/12/transactions to get the latest address transactions