Get project details
Call this endpoint to obtain details and a list of assets for the current project.
/projectCloud Wallet API
API Documentation
Version: v1
Instance: https://api.walletapi.cloud/api/v1
Cloud Wallet is an API that cover asset accounting at scale. We encourage you to integrate our APIs with your existing product or build a new one.
Authenticate your calls with an Access Key that can be obtained via our web app at app.walletapi.cloud. Each key is linked to a specific project. The words "current project" in this document refer to the project for which your Access Key was created.
Customer Keys are special tokens that enable read-only access to our API from your customer's devices. With this key, applications can access only the wallets that belong to a specific customer. Read how to create Customer Keys at help.walletapi.cloud.
Our API expects that you already have your customer database integrated with your app or service. There is no need to copy all the information about your customers into our system. All we need is a unique ID for your customer that matches the information listed in your database. You may supply additional information, such as the customer’s name or a description, but that is only for your convenience.
Please ensure that you have obtained permission from your customers before sending us their personal information.
Note on consistency guarantees. Due to the distributed nature of our platform, some parts of it are following the eventual consistency model. Transactions themselves internally are running with a strict consistency model, so there is no need to worry about the issues like double-spends or lost transfers. However, you may experience short (1-3 seconds) delays between the successful transaction call and seeing the result in List Transactions call. These delays apply both to UI and the API.
Projects
A *project* is the first entity you create in our web application at app.walletapi.cloud. Projects store customer records and wallets that are linked to one application or focus on one idea. *Transactions are available only for wallets within one project.*
Assets
An *asset* can be anything of value owned by someone, such as virtual or real currencies, bonus points, or metro rides. Inventory items like water bottles, bags of coffee beans, or packets of sugar can also be assets. Asset amounts are stored in wallets.
Create an asset
Create a new asset type.
/assetsParameters
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 201 - Asset created
Delete an asset
Deletes an unused asset type. Used assets cannot be removed. Asset types are marked as used when the first wallet using this asset is created.
/assets/{assetId}Parameters
Path parameters
| Name | Description |
|---|---|
| assetId* |
String
Asset ID
Required
|
Responses
Status: 200 - Successful operation
Status: 404 - Project not found
Status: 403 - Asset is used
Get asset details
Obtain the details of an asset with provided ID. May be called with an Access Key or a Customer Key.
/assets/{assetId}Parameters
Path parameters
| Name | Description |
|---|---|
| assetId* |
String
Asset ID
Required
|
Responses
Status: 200 - Successful operation
Status: 404 - Not found
List project assets
Obtain a list of assets for a project. May be called with an Access Key or a Customer Key.
/assetsParameters
Responses
Status: 200 - Successful operation
Rename an asset
Updates asset name.
/assets/{assetId}/nameParameters
Path parameters
| Name | Description |
|---|---|
| assetId* |
String
Asset ID
Required
|
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 200 - Successful operation
Status: 404 - Not found
Customers
A *customer* is a record that reflects your existing users and enables you to create wallets for them. Basically, customers own wallets. You decide how you map customers into your system. People, devices, vehicles, or appliances that contain value can act as customers. We respect your users' privacy and only ask you to provide an ID that you can later identify and map back to the user in your system.
Create a customer
Creates a new customer record or updates an existing record if a customer with provided ID already exists.
/customersParameters
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 200 - Successful update
Status: 201 - Successful create
Get customer details
Call this endpoint to obtain a record for a customer with provided ID. You are only allowed to read a key’s owner record when you call with a Customer Key.
/customers/{customerId}Parameters
Path parameters
| Name | Description |
|---|---|
| customerId* |
String
Customer ID
Required
|
Responses
Status: 200 - Successful operation
Status: 403 - Not allowed
Status: 404 - Customer not found
List customers
Retrieve a list of your customers with pagination. Specify current page and page size as query parameters.
/customersParameters
Query parameters
| Name | Description |
|---|---|
| page* |
Integer
(int32)
Page number query parameter
Required
|
| pageSize |
Integer
(int32)
Page size query parameter
|
Responses
Status: 200 - Successful operation
Update customer details
Call this endpoint to create or update a record for a customer with provided customer ID. You are only allowed to update a key’s owner record when you call with a Customer Key.
/customers/{customerId}Parameters
Path parameters
| Name | Description |
|---|---|
| customerId* |
String
Customer ID
Required
|
Body parameters
| Name | Description |
|---|---|
| body |
Responses
Status: 200 - Successful operation
Suspend a customer
Suspend customer and all their wallets.
/customers/{customerId}/suspendParameters
Path parameters
| Name | Description |
|---|---|
| customerId* |
String
Customer ID
Required
|
Responses
Status: 200 - Successful operation
Status: 404 - Customer not found
Unsuspend a customer
Unsuspend a customer. Please note that customer's wallets will not be reactivated. You must reactivate wallets either via separate calls or by providing wallet IDs in the request body.
/customers/{customerId}/resumeParameters
Path parameters
| Name | Description |
|---|---|
| customerId* |
String
Customer ID
Required
|
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 200 - Successful operation
Status: 404 - Customer not found
Delete a customer
Call this endpoint to delete a customer record. All wallets belonging to this customer must be closed before this call. **Deleted data cannot be restored. Closed wallets will not be deleted.**
/customers/{customerId}Parameters
Path parameters
| Name | Description |
|---|---|
| customerId* |
String
Customer ID
Required
|
Responses
Status: 200 - Successful operation
Status: 400 - At least one customer's wallet is not closed.
Wallets
A *wallet* stores value, as well as the user’s balance history. Each wallet belongs either to a customer or to you (then it is called a *system wallet*). Assign as many wallets to your users or devices as you’d like. The wallet balance can’t dip below zero. A *wallet entry* is a record in a wallet ledger about an event. There are several types of events: - *Issue* records the effect of an issue operation - *Redeem* records redeem operations - *Debit* is posted to the wallet that is on the debit side of a transfer - *Credit* will appear on the credit side of the transfer
Open a wallet for a customer
Create a wallet for a customer with a provided customer ID. Make a call to receive the opened wallet details.
/walletsParameters
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 201 - Successful operation
Status: 400 - Bad request. Asset ID or customer ID refer to a non-existent entity.
Open a system wallet
Open a new system wallet for the current project. System wallets belong to you, not to your customers. They are linked to a project and usually are created to collect commissions or accept fees, among other reasons.
/system-walletsParameters
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 201 - Successful operation
Status: 400 - Asset not found
Get wallet details
Obtain wallet balance and details. When called with a Customer Key, you will only be permitted to query the wallets that belong to a key owner.
/wallets/{walletId}Parameters
Path parameters
| Name | Description |
|---|---|
| walletId* |
String
Wallet ID
Required
|
Responses
Status: 200 - Successful operation
Status: 404 - Not found
List customer's wallets
Obtain details and balances for wallets belonging to a provided customer. When called with a Customer Key, you will only be permitted to query the wallets that belong to a key owner.
/customers/{customerId}/walletsParameters
Path parameters
| Name | Description |
|---|---|
| customerId* |
String
Customer ID
Required
|
Responses
Status: 200 - Successful operation
Status: 204 - No content
Status: 403 - Not allowed
Status: 404 - Customer not found
List current customer's own wallets
When using a Customer Key, this API will list the wallets that the customer owns. This only works with Customer Keys.
/walletsParameters
Responses
Status: 200 - Successful operation
Status: 204 - No content
Status: 403 - Access denied
List system wallets
Obtain a list of system wallets for this project.
/system-walletsParameters
Responses
Status: 200 - Successful operation
Change wallet name
Updates wallet name. When called with a Customer Key, you can only update the wallets that belong to a key owner.
/wallets/{walletId}/nameParameters
Path parameters
| Name | Description |
|---|---|
| walletId* |
String
Wallet ID
Required
|
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 200 - Successful operation
Status: 404 - Not found
Change wallet description
Updates wallet description. When called with a Customer Key, you can only update the wallets that belong to a key owner.
/wallets/{walletId}/descriptionParameters
Path parameters
| Name | Description |
|---|---|
| walletId* |
String
Wallet ID
Required
|
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 200 - Successful operation
Status: 404 - Not found
Change wallet status
Every wallet is created in Open mode. Then it is possible to change the status (mode) to one of the following: - *Open* wallets can hold a balance and participate in transactions.They can be switched to *Suspended* or *Closed*. - *Suspended* wallets keep their balance, but you’re unable to perform transactions with them. They can be changed back to *Open* or to *Closed*. - *Closed* permanently stops transactions with a wallet. Only empty wallets can be closed, and you can't reopen wallets once you’ve closed them.
/wallets/{walletId}/statusParameters
Path parameters
| Name | Description |
|---|---|
| walletId* |
String
Wallet ID
Required
|
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 200 - Successful operation
Status: 400 - Wrong status
Status: 404 - Wallet not found
List operations in wallet's ledger
Obtain a pageable list of operations that were posted to a wallet within a specified time period.
/wallets/{walletId}/entriesParameters
Path parameters
| Name | Description |
|---|---|
| walletId* |
String
Wallet ID
Required
|
Query parameters
| Name | Description |
|---|---|
| from* |
Long
(int64)
Date from
Required
|
| to* |
Long
(int64)
Date to
Required
|
| page* |
Integer
(int32)
Page number query parameter
Required
|
| pageSize |
Integer
(int32)
Page size query parameter
|
Responses
Status: 200 - Successful operation
Status: 400 - Specified end date is earlier than begin date
Status: 404 - Wallet not found
Transactions
A transaction is a set of operations (one or more) that must be performed together. When a transaction is performed, operations are performed in the order in which they’re listed. An operation is a basic atomic action which updates one or two wallet balances. Each operation posts an entry to the ledger of each wallet it affects. An operation can be performed only within a transaction. There are three types of operations: - A *Transfer* moves some value from one wallet to another within the same project. - An *Issue* operation increases a user’s wallet balance by creating value. - *Redeem* decreases one wallet's balance by eliminating some amount of value. When all the operations in a set can be performed successfully, the whole transaction will be completed. If any single operation fails, all the other operations will be reverted back and the transaction will fail.
Initiate a new transaction
Calling this endpoint will start a new transaction.
/transactionsParameters
Body parameters
| Name | Description |
|---|---|
| body * |
Responses
Status: 201 - Successful operation
Status: 400 - Bad request. Wallet was not found, wrong asset in the operation, etc.
Get transaction details
Call this endpoint to obtain a transaction's current state.
/transactions/{txId}Parameters
Path parameters
| Name | Description |
|---|---|
| txId* |
String
Transaction ID
Required
|
Responses
Status: 200 - Successful operation
Status: 404 - Not found
List transactions
Retrieve a pageable list of transactions for a specified time period.
/transactionsParameters
Query parameters
| Name | Description |
|---|---|
| from* |
Long
(int64)
Date from
Required
|
| to* |
Long
(int64)
Date to
Required
|
| page* |
Integer
(int32)
Page number query parameter
Required
|
| pageSize |
Integer
(int32)
Page size query parameter
|