Balance and Basic Information

Retrieving a wallet's basic information and the current assets balances

Information regarding a wallet such as its states' history, stellar public key and registered assets may be retrieved through the GET /wallets/:id endpoint.

The wallet's balance on each of its registered assets may also be retrieved from this endpoint, within each asset object listed in the assets field of the response.


Types of Balances

Due to the intrinsic complexity of the Asset handling in the open banking architecture, we aim to provide the highest level of transparency available in the system. That's why we deliver different kinds of balances, depending on the overrall transaction status of the specified wallet.

It is important to comprehend the meaning of each one of them so the end-user is presented with the correct balance in the context where it is relevant.

field

description

balance

The current balance in the Stellar Network, also referred as the "current blockchain balance" of the wallet.

pendingBalance

The consolidated sum of all pending transactions, including cash-ins and cash-outs of all sorts and locked asset states.

authorizableBalance

The currently available balance for new transaction authorizations, including pending cash-outs but excluding pending-cash-ins and other kinds of locked asset states. Also referred as "available balance".

consolidatedBalance

The consolidated balance after all pending transactions are executed and all wallet locks are lifted. Also referred as "desired balance" or "target balance" of the wallet.

Note: Depending on the nature of the pending transactions, the consolidated state may not be achieved, for example when some of the transactions fail for any reason. This is the main reason there is a segreation between this field and the authorizableBalance field.


Example Response

A sample Wallet response with a set of registered assets:

{
    "id": "16572eef-cfe7-4c8c-9261-7c65f0967deb",
    "status": "ready",
    "stellar": {
        "publicKey": "GBBUBB452JOEZ737DLGKDOYDCHWA76632IFAOOV6UDZ5HIY5W3RJJLBS"
    },
    "assets": [
        {
            "balance": "1000.0000000",
            "authorizableBalance": "980.0000000",
            "consolidatedBalance": "990.0000000",
            "provider": "parati-provider",
            "code": "BRLP",
            "name": "BRL Parati",
            "deletedAt": null,
            "updatedAt": {},
            "createdAt": {},
            "id": "2400ba9b-5052-4195-b619-dd5fc1383c16"
        },
      {
            "balance": "2560.0000000",
            "authorizableBalance": "980.0000000",
            "consolidatedBalance": "990.0000000",
            "provider": "cdt-visa",
            "code": "BRLD",
            "name": "BRL Dock",
            "deletedAt": null,
            "updatedAt": {},
            "createdAt": {},
            "id": "784b7c4c-0242-4195-b619-349bd8cedd10"
        }
    ],
    "updatedAt": "2020-05-06T14:48:15.776Z",
    "createdAt": "2020-05-06T14:48:15.776Z",
    "states": [
        {
            "id": "d6fe9c7b-0242-454e-8d6e-c4ca4bb62722",
            "status": "ready",
            "createdAt": "2020-05-06T14:49:04.151Z",
            "updatedAt": "2020-05-06T14:49:04.151Z",
            "additionalData": {}
        },
        {
            "id": "836338fd-a7ae-4749-9e2b-6e10a4d38a2e",
            "status": "pending_provider_approval",
            "createdAt": "2020-05-06T14:48:52.415Z",
            "updatedAt": "2020-05-06T14:48:52.415Z",
            "additionalData": {}
        },
        {
            "id": "801c1a71-f0fc-4ba0-a377-f686a377c8fb",
            "status": "registered_in_provider",
            "createdAt": "2020-05-06T14:48:52.384Z",
            "updatedAt": "2020-05-06T14:48:52.384Z",
            "additionalData": {}
        },
        {
            "id": "a3087547-9171-4120-9c63-349bd8cedd10",
            "status": "registered",
            "createdAt": "2020-05-06T14:48:47.364Z",
            "updatedAt": "2020-05-06T14:48:47.364Z",
            "additionalData": {
                "transaction": "76a35767-856c-476f-8caf-7ae1e19a26a9",
                "hash": "528ab8e61fe2b489f2ad61ced0513f8e0d0e211b97324a8aa8a21d90b60e0299"
            }
        },
        {
            "id": "784b7c4c-28c1-44dc-8192-aaec7657638e",
            "status": "pending",
            "createdAt": "2020-05-06T14:48:15.779Z",
            "updatedAt": "2020-05-06T14:48:15.779Z",
            "additionalData": {
                "acceptProviderLegalTerms": true,
                "fingerprint": "PostmanRuntime/7.24.1#::1"
            }
        }
    ],
    "user": {
        "id": "b563ec15-4010-4ac6-8452-3b24f1d4e560",
        "name": "John Connor",
        "firstName": "John",
        "lastName": "Connor",
        "email": "[email protected]",
        "role": "consumer",
        "twoFactorRequired": false,
        "updatedAt": "2020-05-06T14:48:15.249Z",
        "createdAt": "2020-05-06T14:48:15.249Z",
        "domain": {
            "id": "ed411be1-5498-4f7b-b1ff-fd79633c62a4",
            "name": "Bit Capital Network",
            "role": "root"
        }
    }
}

Did this page help you?