Balance Custody About

Assets

This document describes API endpoints used for controlling asset sub-addresses. It is available to the clients of Balance who have been whitelisted for programmatic access to their Warm Wallets.

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.

PreviousExternal accountsNextTransaction fees

Last updated