Assets

This document describes the API endpoints that are available to the clients of Balance who have been whitelisted for programmatic access to their Balance Custody instance.

• API URL

• Authentication

• API Endpoints

  • GET /api/v2/assets/fil/sector_termination_fees

    • Accepted parameters

    • Response Format

    • Examples

API URL

You will receive your API 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 Authentication Docs.

---

API Endpoints

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

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

GET /api/v2/assets/fil/sector_termination_fees

Retrieves Filecoin storage provider termination fees.

This API call is rate limited to 1 call every 15 seconds. Additionally, the data returned is cached for 48 hours.

Accepted parameters:

Accepts the following parameters as a GET query string. Must specify the Content-Type: application/json header with the request.

storage_provider_address

Required. String. Address of the storage provider for which fees are to be retrieved.

Response Format:

The response format is a JSON-encoded struct with the following fields:

live_sectors_penalty_fil

An estimate of the FIL amount required to terminate all currently live sectors for the given storage provider.

faulty_sectors_penalty_fil

An estimate of the FIL amount required to terminate all currently faulty sectors for the given storage provider.

last_updated_at

Timestamp of the last time this data was updated in our cache, in ISO 8601 format.

Examples:

Example curl request:

curl -XGET \
     https://your_custom_subdomain.balancecustody.ca/api/v2/assets/fil/sector_termination_fees?storage_provider_address=t01024

Example response body:

{
    "live_sectors_penalty_fil": 123.456,
    "faulty_sectors_penalty_fil": 7.89,
    "last_updated_at": "2023-09-01T01:23:45.00Z"
}