Using the Wallet

Every globaliD identity has a hot wallet which it can use to store funds in various currencies. These funds are held by a custodian, but can be accessed as needed by the owner of the identity.

There are five fundamental types of transactions the user can perform:

  • send: The user can send funds to another globaliD identity.
  • inbound move: The user can move funds from an external funding source into their hot wallet.
  • outbound move: The user can move funds from their hot wallet back to the external funding source.
  • convert: The user can convert funds from one currency to another.
  • spend: The user can spend money using the globaliD card.

At this stage, two API endpoints are available for viewing the user's wallet: one to retrieve the identity's current balance, and the other retrieves a transaction history. Initiating transactions via the API is not currently supported.

Retrieving Balances

To obtain the current balances for an identity's wallet, you can call the GET /v1/wallet/balance API endpoint:

Request:

   GET /v1/wallet/balance
   BEARER <access_token>

Response:

   HTTP/1.1 200 OK

   {
     "custodian_connection_id: "...",
     "balance_sheets": [
       {
         "balance_sheet_id": "...",
         "balance": [
           {
             "currency": "...",
             "balance": 12345
           },
           ...
         ]
       },
       ...
     ]
   }

::TODO -- the above data structures need to be checked. While they don't match the Swagger file, this does seem to be the data returned by the source code itself::

As you can see, you need an access token tied to a user's identity to retrieve the balance for that identity's hot wallet. The balances are grouped into a balance sheet; some custodians may support multiple balance sheets, while others only have one.

Retrieving Transactions

To retrieve a list of transaction associated with the user's hot wallet, you can call the GET /v1/wallet/transactions API endpoint. For example:

Request:

   GET /v1/wallet/transactions
   BEARER <access_token>

Response:

   HTTP/1.1 200 OK

   [
     {
       "uuid": "...",
       "source_id": "...",
       "destination_id": "...",
       "source_currency": "...",
       "destination_currency": "...",
       "finished_at": "...",
       "fee_object": "...",
       "status": "...",
       "type": "...",
       "created_at": "...",
       "updated_at": "..."
     },
     ...
   ]

Once again, you need to have an access token bound to an identity to be able to retrieve that identity's hot-wallet transactions.

The various fields returned for each transaction include:

  • uuid: a unique UUID value identifying this transaction.
  • source_id: a UUID identifying the source of the transaction. ::Is this the balance sheet ID?::
  • destination_id: a UUID identifying the destination of the transaction. ::what is this exactly::
  • source_currency: the source currency.
  • destination_currency: the destination currency.
  • finished_at: the date and time at which this transaction was completed, in ISO-8601 format.
  • fee_object: an object providing information about the fees which were charged for this transaction, encoded as a JSON-formatted string.
  • status: the status of this transaction. One of:

    `RECEIVED`
    `IN_PROGRESS`
    `SUCCESS`
    `FAILED`
    
  • type: the type of transaction. One of:

    `SEND`
    `CONVERT`
    `LOAD`
    `SPEND`
    `CREATE_ACCOUNT`
    `UPDATE_ACCOUNT`
    `INBOUND_MOVE`
    `OUTBOUND_MOVE`
    
  • created_at: the date and time at which this transaction was created, in ISO-8601 format.

  • updated_at: the date and time at which this transaction was last updated, in ISO-8601 format.

Note that the returned list of transactions includes both financial transactions and internal transactions used to manage the user's hot wallet.