Assets

This document details the Balance Custody v1 Assets API, offering endpoints to manage wallet assets, including balance retrieval, asset updates, Filecoin storage provider info, and withdrawals.

Supported Currencies

Currently only the following currencies support sub-addresses:

Bitcoin (btc)
Bitcoin Cash (bch)
Litecoin (ltc)
Dash (dash)

API URL

You will receive your warm wallet integration URL from your point of contact at Balance, and will look like:

YOUR_CUSTOM_SUBDOMAIN.balancecustody.ca

Authentication

Due to the nature of the information exposed, every endpoint in this API requires authentication.

For more information on authentication go to the Authentication doc.

API Endpoints

For brevity, the curl examples below do not include headers. See the Authentication section for required headers.

Response data is for example purposes only and does not represent real crypto addresses.

`GET /api/v1/wallets/:wallet_id/assets/:currency`

List all active funding addresses for given currency and wallet.

Request

Example:

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/btc

Response

Returns an array of transaction JSON structs.

Status: 200

Example of api response:

[
    {
        "name": "Bitcoin 1",
        "notes": null,
        "address": "14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA",
        "balance": 12.34567890,
        "is_watched": false
    },
    {
        "name": "API Created",
        "notes": "some notes",
        "address": "1Aipi2Sxt5XrDzaFmvReWos8Jzi6uZtLXU",
        "balance": 12.34567890,
        "is_watched": true
    }
]

`POST /api/v1/wallets/:wallet_id/assets/:currency`

Will create a new funding address for the given currency and return a list of all active funding addresses for the specified wallet and currency pair.

Accepted parameters

name - string, sets the name field of the newly created address
notes - string, sets the notes field of the newly created address
is_watched - boolean, sets the is_watched field of the newly created address. The current user that made the api call will be added as a watcher.

Parameters must be serialized into a JSON object with the above fields set as top-level keys in the object. This JSON string must be passed in as part of request body.

Request

curl -XPOST \
    -d '{"name": "Test BTC address 2", "notes": "Address created via the api", "is_watched": true}' \
    -H "content-type: application/json" \
    https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/btc

Successful Response

Returns a transaction JSON struct.

Status: 200

Data:

[
    {
        "name": "Bitcoin 1",
        "notes": null,
        "address": "14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA",
        "balance": 12.34567890,
        "is_watched": false
    },
    {
        "name": "Test BTC address 2",
        "notes": "Address created via the api",
        "address": "1Aipi2Sxt5XrDzaFmvReWos8Jzi6uZtLXU",
        "balance": 0,
        "is_watched": true
    }
]

Failed Response - Not supported currency

Returns a transaction JSON struct.

Status: 400

Data:

{
  "error": "Currency eth does not support sub-addresses."
}

`PUT /api/v1/wallets/:wallet_id/assets/:currency/:address`

Will update an existing funding address for the given currency and return the updated address.

Accepted parameters

name - string, sets the name field of the newly created address
notes - string, sets the notes field of the newly created address
is_watched - boolean, sets the is_watched field of the newly created address. The current user that made the api call will be added as a watcher.

Parameters must be serialized into a JSON object with the above fields set as top-level keys in the object. This JSON string must be passed in as part of request body.

No extra parameters are accepted.

Request

curl -d '{"name": "Updated Name", "notes": "Updated notes", "is_watched": true}' \
    -H "content-type: application/json" \
    https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/btc/14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA

Successful Response

Returns a transaction JSON struct.

Status: 200

Data:

{
    "name": "Updated Name",
    "notes": "Updated notes",
    "address": "14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA",
    "balance": 12.34567890,
    "is_watched": true
}

Failed Response - Not supported currency

Returns a transaction JSON struct.

Status: 400

Data:

{
  "error": "Currency eth does not support sub-addresses."
}

`GET /api/v1/wallets/:wallet_id/assets/fil/storage_providers`

List all Filecoin storage providers for a wallet. No parameters accepted.

Request

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers

Response

Returns an array of JSON structs.

Data:

{
    "storage_providers": [
        {
            "id": 125,
            "storage_provider": "t2eogkus2w5xvly46piaf44uzacocqdrkbzx32ufi",
            "initial_pledge": 0,
            "locked_rewards": 0,
            "available_balance": 10420.49831870958
        }
    ]
}

`GET /api/v1/wallets/:wallet_id/assets/fil/storage_providers/:storage_provider_id`

Get a single Filecoin storage provider.

Accepted parameters

show_sector_summary - boolean, returns various sector related information when "true" is included

Request

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers/125

Response

Returns a single JSON struct.

Data:

{
    "storage_provider": {
        "id": 125,
        "storage_provider": "t2eogkus2w5xvly46piaf44uzacocqdrkbzx32ufi",
        "initial_pledge": 0,
        "locked_rewards": 0,
        "available_balance": 10420.49831870958
    }
}

Request with show_sector_summary=true

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers/125?show_sector_summary=true

Response

Returns a single JSON struct.

Data:

{
    "storage_provider": {
        "active_sectors": 0,
        "available_balance": 123.456,
        "faulty_sectors": 100,
        "faulty_sectors_penalty_fil": 789.123,
        "id": 125,
        "initial_pledge": 0.0,
        "last_updated_at": "2023-05-01T15:01:25Z",
        "live_sectors": 200,
        "live_sectors_penalty_fil": 456.789,
        "locked_rewards": 0.0,
        "storage_provider": "t01491"
    }
}

`POST /api/v1/wallets/:wallet_id/assets/fil/storage_providers/:storage_provider_id/withdrawals`

Create a reward withdrawal transaction.

Accepted parameters

amount_afil - number, must be an integer amount of attoFIL to withdraw.
fee - string or float, sets the fee rate or sets a preset fee rate, see description below. Optional, default is "medium".
notes - string, signifies your internal notes for this transaction. Optional, default is no custom note.

Parameters must be serialized into a JSON object with the above fields set as top-level keys in the object. This JSON string must be passed in as part of request body.

No extra parameters are accepted.

See Fee API docs for units of measurement in which fees are specified.

Fee rates can be specified as numbers (integer or float), as well as the following preset values: "slow", "medium", "fast". When preset values are specified they are automatically replaced with corresponding values from the Fee API.

Request

curl -XPOST \
     -d '{"amount_afil": 123000000000, "fee_rate": "fast", "notes": "Withdraw initial reward."}' \
     https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers/125

Response

Returns a single JSON struct.

Data:

{
    "id": 987,
    "type": "transaction",
    "status": "inactive",
    "created_at": "2023-02-27T21:16:58.000Z",
    "requested_by": "",
    "source": {
        "id": 125,
        "type": "wallet",
        "kind": "external",
        "custom_id": "FIL miner t01491",
        "name": "FIL miner t01491",
        "description": "Calibration miner.",
        "balance": {
            "fil": 0,
            "usdt": 0,
        },
        "funding_addresses": {
            "fil": "t2guar5o73kvvwrmwozwjbesyu4jurodqqigyyrua",
            "usdt": "0xc1cA86078202166F41C6D87069C2aa2eFFf055a4",
        }
    },
    "amounts": {
        "fil": 1.23e-07
    },
    "cad_rates": {
        "fil": 9.1567084
    },
    "notes": "Withdraw initial reward.\n\nBalance withdrawal from FIL miner t01491 for 0.000000123 FIL.",
    "is_batched": false,
    "destination": {
        "id": 114,
        "type": "wallet",
        "kind": "warm",
        "custom_id": "fir",
        "name": "FIL receiver",
        "description": "",
        "balance": {
            "fil": 1,
            "usdt": 0,
        },
        "funding_addresses": {
            "fil": "t3sg27lp6xgz3fb7db7t4x4lhmsf3dgu73mj5sodkshh64ftr6dzkrfxrowroon2cr2f3vkumsi4schkpfyvea",
            "usdt": "0x959afc6F5cCE124107F6c0862A5bDf0dD58bD2Bd",
        }
    },
    "fees": {
        "fil": 6.2606875e-07
    },
    "fee_units": {
        "fil": "nanoFil"
    },
    "block": {
        "fil": null
    },
    "data": {
        "fil": "8146001ca35f0e00"
    },
    "regulatory_status": "not_required",
    "originator_entity": {
        "kind": "corporate",
        "address1": "325 Front St. W",
        "address2": "4th floor",
        "city": "Toronto",
        "state": "Ontario",
        "postcode": "M5V 2Y1",
        "country": "Canada",
        "corporate_name": "PARADISO VENTURES INC. O/A Balance",
        "incorporation_number": "1031616-4",
        "nature_of_business": "Digital goods and services"
    }
}

`GET /api/v2/assets/:currency`

List wallets having positive balances of the specified currency.

Accepted parameters

Accepts the following GET parameters as part of the query string:

order_by

Optional. Specifies how to sort the wallets. If not specified will sort by wallet ID descending.

Possible values are:

id - Wallet ID descending.
balance - Balance descending..

page

Optional. If specified returns results from the specified page. Page numbers begin at 1. If not specified returns the first page.

Request

Example with defaults:

curl https://your_custom_subdomain.balancecustody.ca/api/v2/assets

Example with options:

curl https://your_custom_subdomain.balancecustody.ca/api/v2/assets?order_by=balance&page=2

Response

Returns an array of wallet JSON structs.

Status: 200

Data:

{
    "wallets":
    [
        {
            "id": 1,
            "type": "wallet",
            "kind": "warm",
            "custom_id": "editable custom id 1",
            "name": "editable name 1",
            "description": "editable description 1",
            "balance": {
                "btc":  12.34567890,
                "bch":  12.34567890,
                "ltc":  12.34567890,
                "dash": 12.34567890,
                "eth":  12.34567890
            },
            "funding_addresses": {
                "btc":  "1JfQeTopCr1SNk9qoF7qsfCcGtmNUvZdbg",
                "bch":  "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ",
                "ltc":  "LY5kxT567jCCH6Au1iJHj36ZZKoT5mkeN3",
                "dash": "Xhwc7iQTKGq28YWjQNPrNCbGV5v6PWj363",
                "eth":  "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4"
            }
        },
        {
            "id": 2,
            "type": "wallet",
            "kind": "warm",
            "custom_id": "editable custom id 2",
            "name": "editable name 2",
            "description": "editable description 2",
            "balance": {
                "btc":  12.34567890,
                "bch":  12.34567890,
                "ltc":  12.34567890,
                "dash": 12.34567890,
                "eth":  12.34567890
            },
            "funding_addresses": {
                "btc":  "1EWwLtiDvrLKKf6ySDoKqnFYLvcDMr2TvY",
                "bch":  "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
                "ltc":  "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
                "dash": "Xhwc7iQTKGq28YWjQNPrNCbGV5v6PWj363",
                "eth":  "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09"
            }
        }
    ]
}

Errors

Errors in this API are the same as the ones specified in the wallet API docs.

PreviousWallets NextTransaction fees

Last updated 10 months ago

Assets

This document details the Balance Custody v1 Assets API, offering endpoints to manage wallet assets, including balance retrieval, asset updates, Filecoin storage provider info, and withdrawals.

Supported Currencies

Currently only the following currencies support sub-addresses:

Bitcoin (btc)
Bitcoin Cash (bch)
Litecoin (ltc)
Dash (dash)

API URL

You will receive your warm wallet integration URL from your point of contact at Balance, and will look like:

YOUR_CUSTOM_SUBDOMAIN.balancecustody.ca

Authentication

Due to the nature of the information exposed, every endpoint in this API requires authentication.

For more information on authentication go to the Authentication doc.

API Endpoints

For brevity, the curl examples below do not include headers. See the Authentication section for required headers.

Response data is for example purposes only and does not represent real crypto addresses.

`GET /api/v1/wallets/:wallet_id/assets/:currency`

List all active funding addresses for given currency and wallet.

Request

Example:

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/btc

Response

Returns an array of transaction JSON structs.

Status: 200

Example of api response:

[
    {
        "name": "Bitcoin 1",
        "notes": null,
        "address": "14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA",
        "balance": 12.34567890,
        "is_watched": false
    },
    {
        "name": "API Created",
        "notes": "some notes",
        "address": "1Aipi2Sxt5XrDzaFmvReWos8Jzi6uZtLXU",
        "balance": 12.34567890,
        "is_watched": true
    }
]

`POST /api/v1/wallets/:wallet_id/assets/:currency`

Will create a new funding address for the given currency and return a list of all active funding addresses for the specified wallet and currency pair.

Accepted parameters

name - string, sets the name field of the newly created address
notes - string, sets the notes field of the newly created address
is_watched - boolean, sets the is_watched field of the newly created address. The current user that made the api call will be added as a watcher.

Parameters must be serialized into a JSON object with the above fields set as top-level keys in the object. This JSON string must be passed in as part of request body.

Request

curl -XPOST \
    -d '{"name": "Test BTC address 2", "notes": "Address created via the api", "is_watched": true}' \
    -H "content-type: application/json" \
    https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/btc

Successful Response

Returns a transaction JSON struct.

Status: 200

Data:

[
    {
        "name": "Bitcoin 1",
        "notes": null,
        "address": "14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA",
        "balance": 12.34567890,
        "is_watched": false
    },
    {
        "name": "Test BTC address 2",
        "notes": "Address created via the api",
        "address": "1Aipi2Sxt5XrDzaFmvReWos8Jzi6uZtLXU",
        "balance": 0,
        "is_watched": true
    }
]

Failed Response - Not supported currency

Returns a transaction JSON struct.

Status: 400

Data:

{
  "error": "Currency eth does not support sub-addresses."
}

`PUT /api/v1/wallets/:wallet_id/assets/:currency/:address`

Will update an existing funding address for the given currency and return the updated address.

Accepted parameters

name - string, sets the name field of the newly created address
notes - string, sets the notes field of the newly created address
is_watched - boolean, sets the is_watched field of the newly created address. The current user that made the api call will be added as a watcher.

Parameters must be serialized into a JSON object with the above fields set as top-level keys in the object. This JSON string must be passed in as part of request body.

No extra parameters are accepted.

Request

curl -d '{"name": "Updated Name", "notes": "Updated notes", "is_watched": true}' \
    -H "content-type: application/json" \
    https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/btc/14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA

Successful Response

Returns a transaction JSON struct.

Status: 200

Data:

{
    "name": "Updated Name",
    "notes": "Updated notes",
    "address": "14v9vRC3R1HJqRrgG9mDnuzzHSFvMHvRSA",
    "balance": 12.34567890,
    "is_watched": true
}

Failed Response - Not supported currency

Returns a transaction JSON struct.

Status: 400

Data:

{
  "error": "Currency eth does not support sub-addresses."
}

`GET /api/v1/wallets/:wallet_id/assets/fil/storage_providers`

List all Filecoin storage providers for a wallet. No parameters accepted.

Request

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers

Response

Returns an array of JSON structs.

Data:

{
    "storage_providers": [
        {
            "id": 125,
            "storage_provider": "t2eogkus2w5xvly46piaf44uzacocqdrkbzx32ufi",
            "initial_pledge": 0,
            "locked_rewards": 0,
            "available_balance": 10420.49831870958
        }
    ]
}

`GET /api/v1/wallets/:wallet_id/assets/fil/storage_providers/:storage_provider_id`

Get a single Filecoin storage provider.

Accepted parameters

show_sector_summary - boolean, returns various sector related information when "true" is included

Request

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers/125

Response

Returns a single JSON struct.

Data:

{
    "storage_provider": {
        "id": 125,
        "storage_provider": "t2eogkus2w5xvly46piaf44uzacocqdrkbzx32ufi",
        "initial_pledge": 0,
        "locked_rewards": 0,
        "available_balance": 10420.49831870958
    }
}

Request with show_sector_summary=true

curl https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers/125?show_sector_summary=true

Response

Returns a single JSON struct.

Data:

{
    "storage_provider": {
        "active_sectors": 0,
        "available_balance": 123.456,
        "faulty_sectors": 100,
        "faulty_sectors_penalty_fil": 789.123,
        "id": 125,
        "initial_pledge": 0.0,
        "last_updated_at": "2023-05-01T15:01:25Z",
        "live_sectors": 200,
        "live_sectors_penalty_fil": 456.789,
        "locked_rewards": 0.0,
        "storage_provider": "t01491"
    }
}

`POST /api/v1/wallets/:wallet_id/assets/fil/storage_providers/:storage_provider_id/withdrawals`

Create a reward withdrawal transaction.

Accepted parameters

amount_afil - number, must be an integer amount of attoFIL to withdraw.
fee - string or float, sets the fee rate or sets a preset fee rate, see description below. Optional, default is "medium".
notes - string, signifies your internal notes for this transaction. Optional, default is no custom note.

Parameters must be serialized into a JSON object with the above fields set as top-level keys in the object. This JSON string must be passed in as part of request body.

No extra parameters are accepted.

See Fee API docs for units of measurement in which fees are specified.

Request

curl -XPOST \
     -d '{"amount_afil": 123000000000, "fee_rate": "fast", "notes": "Withdraw initial reward."}' \
     https://your_custom_subdomain.balancecustody.ca/api/v1/wallets/1/assets/fil/storage_providers/125

Response

Returns a single JSON struct.

Data:

{
    "id": 987,
    "type": "transaction",
    "status": "inactive",
    "created_at": "2023-02-27T21:16:58.000Z",
    "requested_by": "",
    "source": {
        "id": 125,
        "type": "wallet",
        "kind": "external",
        "custom_id": "FIL miner t01491",
        "name": "FIL miner t01491",
        "description": "Calibration miner.",
        "balance": {
            "fil": 0,
            "usdt": 0,
        },
        "funding_addresses": {
            "fil": "t2guar5o73kvvwrmwozwjbesyu4jurodqqigyyrua",
            "usdt": "0xc1cA86078202166F41C6D87069C2aa2eFFf055a4",
        }
    },
    "amounts": {
        "fil": 1.23e-07
    },
    "cad_rates": {
        "fil": 9.1567084
    },
    "notes": "Withdraw initial reward.\n\nBalance withdrawal from FIL miner t01491 for 0.000000123 FIL.",
    "is_batched": false,
    "destination": {
        "id": 114,
        "type": "wallet",
        "kind": "warm",
        "custom_id": "fir",
        "name": "FIL receiver",
        "description": "",
        "balance": {
            "fil": 1,
            "usdt": 0,
        },
        "funding_addresses": {
            "fil": "t3sg27lp6xgz3fb7db7t4x4lhmsf3dgu73mj5sodkshh64ftr6dzkrfxrowroon2cr2f3vkumsi4schkpfyvea",
            "usdt": "0x959afc6F5cCE124107F6c0862A5bDf0dD58bD2Bd",
        }
    },
    "fees": {
        "fil": 6.2606875e-07
    },
    "fee_units": {
        "fil": "nanoFil"
    },
    "block": {
        "fil": null
    },
    "data": {
        "fil": "8146001ca35f0e00"
    },
    "regulatory_status": "not_required",
    "originator_entity": {
        "kind": "corporate",
        "address1": "325 Front St. W",
        "address2": "4th floor",
        "city": "Toronto",
        "state": "Ontario",
        "postcode": "M5V 2Y1",
        "country": "Canada",
        "corporate_name": "PARADISO VENTURES INC. O/A Balance",
        "incorporation_number": "1031616-4",
        "nature_of_business": "Digital goods and services"
    }
}

`GET /api/v2/assets/:currency`

List wallets having positive balances of the specified currency.

Accepted parameters

Accepts the following GET parameters as part of the query string:

order_by

Optional. Specifies how to sort the wallets. If not specified will sort by wallet ID descending.

Possible values are:

id - Wallet ID descending.
balance - Balance descending..

page

Optional. If specified returns results from the specified page. Page numbers begin at 1. If not specified returns the first page.

Request

Example with defaults:

curl https://your_custom_subdomain.balancecustody.ca/api/v2/assets

Example with options:

curl https://your_custom_subdomain.balancecustody.ca/api/v2/assets?order_by=balance&page=2

Response

Returns an array of wallet JSON structs.

Status: 200

Data:

{
    "wallets":
    [
        {
            "id": 1,
            "type": "wallet",
            "kind": "warm",
            "custom_id": "editable custom id 1",
            "name": "editable name 1",
            "description": "editable description 1",
            "balance": {
                "btc":  12.34567890,
                "bch":  12.34567890,
                "ltc":  12.34567890,
                "dash": 12.34567890,
                "eth":  12.34567890
            },
            "funding_addresses": {
                "btc":  "1JfQeTopCr1SNk9qoF7qsfCcGtmNUvZdbg",
                "bch":  "1H1NtR2TxvpxVffhh13xKeX2vxENvRJcBZ",
                "ltc":  "LY5kxT567jCCH6Au1iJHj36ZZKoT5mkeN3",
                "dash": "Xhwc7iQTKGq28YWjQNPrNCbGV5v6PWj363",
                "eth":  "0x4D4aA364A4afDf8aa9a4f840640a700F44E793f4"
            }
        },
        {
            "id": 2,
            "type": "wallet",
            "kind": "warm",
            "custom_id": "editable custom id 2",
            "name": "editable name 2",
            "description": "editable description 2",
            "balance": {
                "btc":  12.34567890,
                "bch":  12.34567890,
                "ltc":  12.34567890,
                "dash": 12.34567890,
                "eth":  12.34567890
            },
            "funding_addresses": {
                "btc":  "1EWwLtiDvrLKKf6ySDoKqnFYLvcDMr2TvY",
                "bch":  "16CyXcfgoRzBmxC3PzwwQgf8vdovtcGcRi",
                "ltc":  "LbeFePhgCMjnVgNtVCYUpJsPxA7VScd8jE",
                "dash": "Xhwc7iQTKGq28YWjQNPrNCbGV5v6PWj363",
                "eth":  "0x3Dbd0Ec235A15C16F419f990d67B48eb5c04ae09"
            }
        }
    ]
}

Errors

Errors in this API are the same as the ones specified in the wallet API docs.

PreviousWallets NextTransaction fees

Last updated 10 months ago