upvest

Go library for the Upvest API.

In order to retrieve your API credentials for using this Go client, you'll need to sign up with Upvest.

Where possible, the services available on the client groups the API into logical chunks and correspond to the structure of the Upvest API documentation.

First, create an Upvest client and depending on what action to take, you either create tenancy or clientele client. All tenancy related operations must be authenticated using the API Keys Authentication, whereas all actions on a user's behalf need to be authenticated via OAuth. The API calls are built along with those two authentication objects.

// NewClient creates a new Upvest API client with the given base URL
// and HTTP client, allowing overriding of the HTTP client to use.
// This is useful if you're running in a Google AppEngine environment
// where the http.DefaultClient is not available.

c := NewClient("", nil)

// Configure logging using the Loggingenabled config key
c.Loggingenabled = true

Tenancy API - API Keys Authentication

The Upvest API uses the notion of tenants, which represent customers that build their platform upon the Upvest API. The end-users of the tenant (i.e. your customers), are referred to as clients. A tenant is able to manage their users directly (CRUD operations for the user instance) and is also able to initiate actions on the user's behalf (create wallets, send transactions).

The authentication via API keys and secret allows you to perform all tenant related operations. Please create an API key pair within the Upvest account management.

The default BASE_URL for both authentication objects is https://api.playground.upvest.co, but feel free to adjust it, once you retrieve your live keys. Next, create an Tenancy object in order to authenticate your API calls:

tenant = c.NewTenant(apiKey, apiSecret, apiPassphrase)

// create a user
user, err := tenant.User.Create(username, randomString(12))
if err != nil {
    t.Errorf("CREATE User returned error: %v", err)
}

// list users
users, err := tenant.User.List()
if err != nil {
    t.Errorf("List Users returned error: %v", err)
}

// retrieve 20 users
users, err := tenant.User.ListN(20)
if err != nil {
    t.Errorf("List Users returned error: %v", err)
}

// change password
user, err = tenant.User.ChangePassword(username, params)

Clientele API - OAuth Authentication

The authentication via OAuth allows you to perform operations on behalf of your user. For more information on the OAuth concept, please refer to our documentation. Again, please retrieve your client credentials from the Upvest account management.

Next, create an Clientele object with these credentials and your user authentication data in order to authenticate your API calls on behalf of a user:

clientele = c.NewClientele(clientID, clientSecret, username, password)
wp := &WalletParams{
    Password: staticUserPW,
    AssetID: "8fc19cd0-8f50-4626-becb-c9e284d2315b",
}

// create the wallet
wallet, err := clientele.Wallet.Create(wp)
if err != nil {
    t.Errorf("CREATE Wallet returned error: %v", err)
}

// // retrieve the wallet
wallet1, err := clientele.Wallet.Get(wallet.ID)
if err != nil {
    t.Errorf("GET Wallet returned error: %v", err)
}

Usage

Tenancy

User management

user, err := tenant.User.Create('username','password')

user, err := tenant.User.Get('username')

users, err := tenant.User.List()

for _, user := range users.Values {
  //do something with user
}

users, err := tenant.User.listN(10)

params := &upvest.ChangePasswordParams{
    OldPassword: "current password",
    NewPassword: "new pasword",
}
user, err := tenant.User.ChangePassword(username, params)

tenant.User.Delete('username')

Clientele

Assets

assets, err := clientele.Asset.List()
for _, asset := range assets.Values {
  //do something with asset
}

Wallets

wp := &upvest.WalletParams{
    Password: "current user password",
    AssetID:  "asset ID",
    // Type:     "encrypted",
    // Index:    0,
}

// create the wallet
wallet, err := clientele.Wallet.Create(wp)

wallet1, err := clientele.Wallet.Get(walletID)

wallets, err := clientele.Wallet.List()
for _, wallet := range wallets.Values {
  //do something with wallet
}

wallets, err := clientele.Wallet.ListN(40)

Transactions

tp := &upvest.TransactionParams{
    Password:  "current user password",
    AssetID:   "asset ID",
    Quantity:  "quantity, e.g. 10000000000000000",
    Fee:       "fee, e.g. 41180000000000",
    Recipient: "transaction address, e.g. 0xf9b44Ba370CAfc6a7AF77D0BDB0d50106823D91b",
}

// create the transaction
txn, err := clientele.Transaction.Create("wallet ID", tp)

Retrieve specific transaction

wallet1, err := clientele.Wallet.Get("wallet ID")

transactions, err := clientele.Transaction.List("wallet ID")
for _, txn := range transactions.Values {
  //do something with transaction
}

transactions, err := clientele.Transaction.ListN("wallet ID", 8)

Development

1. Code must be go fmt compliant: make fmt

2. All types, structs and funcs should be documented.

3. Ensure that make test succeeds.

4. Set up config settings via environment variables:

   # Set your tenancy API key information here.
   export API_KEY=xxxx
   export API_SECRET=xxxx
   export API_PASSPHRASE=xxxx
   
   # Set your OAuth2 client information here.
   export OAUTH2_CLIENT_ID=xxxx
   export OAUTH2_CLIENT_SECRET=xxxx
   

Test

Run all tests:

make test

Run a single test:

DEBUG=1 go test -run TestChangePassword

More

For a comprehensive reference, check out the Upvest documentation.

For details on all the functionality in this library, see the GoDoc documentation.