This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Tutorials

Helpful tutorials and getting started guides to get you up and running on the Pocket Gateway.

1: Getting Started

1.1: Create a new user
1.2: Access the user account
1.3: Verify the user entity
1.4: Fund your account
1.5: Create a portfolio
1.6: Deploy a resource
1.7: Check on your resource
1.8:

This section of the Pocket Gateway documentation contains tutorials. A tutorial shows how to accomplish a goal that is larger than a single task. Typically a tutorial has several sections, each of which has a sequence of steps.

1 - Getting Started

This guide will walk you through basic usage with the Pocket Gateway

In less than <15 minutes you’ll be able to deploy a fully personalized investment manager investing and trading directly on your or your customer’s behalf!

Learning Outcomes

💪 Afterwards, you’ll be able to:

1.1 - Create a new user

Create a new user on the Pocket Gateway

Create a new user

First, you will need to create a new user and an accompanying account.

Only free and personal accounts are supported!

Only free and personal accounts are currently supported. professional and bespoke plans are not yet available.

Replace the environment variables with your given and family name, email, and temporary password.

You will be asked to change the password once the user identifies themselves.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


export \
	USER_GIVEN_NAME="sarah" \
	USER_FAMILY_NAME="kerrigan" \
 	USER_EMAIL="sarah.kerrigan@char.com" \
 	USER_PASSWORD="zeratul"

curl \
  --request POST \
  --url "https://alpha.api.pocket-portfolio.com/objects/user" \
  --header "Content-Type: application/json" \
  --data '{
  	"given_name": "${USER_GIVEN_NAME}",
    "family_name": "${USER_FAMILY_NAME}",
    "email": "${USER_EMAIL}",
    "password": "${USER_PASSWORD}",
    "tier": "free"
  }'

If your user was created successfully, you should see:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
	"created_at": "2021-02-06T16:52:14.129Z",
	"email": "sarah.kerrigan@char.com",
	"given_name": "sarah",
	"user_id": "Y60107f369dbd1a0068f0232z",
	"family_name": "kerrigan",
	"picture": "https://s.gravatar.com/.../avatars%2Fpe.png",
	"user_metadata": {
		"tier": "tier-0",
		"verified": false
	}
}

export USER_USER_ID="Y60107f369dbd1a0068f0232z"

1

"Bad Request - Received a bad request from the user"

Make note of the user_id , you will need it later!
free and personal accounts will automatically create a linked account.

Generate an access token

We’re now going to generate a JWT to authenticate with the Pocket Gateway.

1
2
3
4
5


curl \
  --request POST \
  --url "https://alpha.api.pocket-portfolio.com/object/token/password" \
  --header "Content-Type: application/json" \
  --data '{"user_id": ${USER_USER_ID}, "password": "${USER_PASSWORD}"}'

You should get a response containing the token in the access_token attribute.

1
2
3
4
5
6
7


{
	"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ildfd...",
	"expires_in": 43200,
	"token_type": "Bearer",
}

export ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ildfd..."

1

"Bad Request - Received a bad request from the user"

Not the most secure option!

This method of generating an access token is not the most secure. We use it here for illustrative purposes; rather if you’re building an application or requesting an access token often, prefer the object/token/oauth access flow.

👍 Wonderful! You’ve created a new user on the Pocket Cloud and now have an access token to start deploying resources!

1.2 - Access the user account

Access the newly created user accounts.

Access user account

If you are creating professional or bespoke accounts, you will have to create the accounts manually.

First, let’s get all accounts associated to the user:

1
2
3
4
5


curl -X \
  --request GET \
  --url "https://alpha.api.pocket-portfolio.com/object/account/list" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should receive an array populated with universally unique identifiers (RFC 4122 complaint) to the user accounts.

1
2
3
4
5
6
7
8


[
  "059cc47f-b1f3-490b-ac1f-dd3e1457297d",
  "ff598b1b-86fe-45fe-8b8f-27fe6e8dc7f2"
]

export \
  USER_ACCOUNT_ID="059cc47f-b1f3-490b-ac1f-dd3e1457297d" \
  USER_SANDBOX_ACCOUNT_ID="ff598b1b-86fe-45fe-8b8f-27fe6e8dc7f2"

1

"Unauthorized access - Unauthorized - you do not have access to this API"

Check account status:

1
2
3
4
5


curl -X \
  --request GET \
  --url "https://alpha.api.pocket-portfolio.com/object/account/status" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should see two accounts; the first account is the production account as indicated with the is_sandbox=false flag–which you’ll be billed for, and the second account is the sandbox account, which you can use as an isolated, non-billable environment to test different resources (AIs).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


[
  {
    "account_id": "059cc47f-b1f3-490b-ac1f-dd3e1457297d",
    "is_verified": false,
    "is_omnibus": false,
    "is_managed": false,
    "is_headless": true,
    "is_hold": false,
    "is_closed": false,
    "is_sandbox": false
  },
  {
    "account_id": "ff598b1b-86fe-45fe-8b8f-27fe6e8dc7f2",
    "is_verified": false,
    "is_omnibus": false,
    "is_managed": false,
    "is_headless": true,
    "is_hold": false,
    "is_closed": false,
    "is_sandbox": true
  }
]

1

"Unauthorized access - Unauthorized - you do not have access to this API"

Account is not yet verified!

You may notice that the account is_verified is still in the false state. Most Pocket endpoints will be unavailable until the user has completed verification. At which point, once the user’s identity is verified, the account will be marked true.

Get account details:

1
2
3
4
5


curl -X \
  --request GET \
  --url "https://alpha.api.pocket-portfolio.com/object/account/${USER_ACCOUNT_ID}" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should get the below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


[
  {
    "account_id": "059cc47f-b1f3-490b-ac1f-dd3e1457297d",
    "parent_account_id": null,
    "account_type": "SMA",
    "user_id": "60107f369dbd1a0068f0232a",
    "accounting_method": "WAC",
    "created_at": "2021-02-06T16:52:14.129Z",
    "updated_at": "2022-02-06T16:52:14.129Z",
    "closed_at": null
  }
]

1

"Unauthorized access - Unauthorized - you do not have access to this API"

👍 Báječné! You’ve accessed your newly created account on the Pocket Cloud!

1.3 - Verify the user entity

Verify the user’s entity information

Verify user entity

Before you can deploy most resources, you will have to verify the calling user entity. In most circumstances, all you’ll need to do is provide a government issued ID and verify your proof of identity.

For some account types such as professional and bespoke , you will need to provide additional information.

graph LR
    L[Legal Entity] --> U1[User 1]

    U1[User 1] --> A1[Main Account]
    U1[User 1] --> A2[Sandbox Account]

    L[Legal Entity] --> Verification{Is verified?}

    Verification{Is verified?} --> Access([Resource Access])

Kick-off verification

To start the verification process, send a POST request to the object/entity endpoint.

@TODO

Check verification status

Once the verification has been completed, you can check the status of user accounts by querying the object/account endpoint. Now, you should see that the user account has been verified.

@TODO

👍 Wunderbar! You’ve verified your entity on the Pocket Cloud!

1.4 - Fund your account

Deposit funds into the user account

@TODO

1.5 - Create a portfolio

Create a financial portfolio

Create a portfolio

Before you can start deploying resources onto the Pocket Cloud, you must create a financial portfolio that is linked to your account.

@TODO

1.6 - Deploy a resource

Deploy a synthetic resource onto the Pocket Gateway

We’re now going to deploy a resource–an artificial intelligence, on the Pocket Cloud.

A resource is a set of one or more trained policies which carry out a set of pre-defined tasks. In other words, a resource is an “AI” that performs actions on behalf of the calling user.

Resources are identified by a family and name . Resources within the same family are logically related. Once a resource is deployed on the Pocket Cloud It is assigned an id , a universally unique RFC 4122 complaint identifier.

Employ a resource

For this example, we’ll be using the simple-manager resource which constructs a random financial portfolio. This resource is always used in sandbox mode so you don’t need to worry about incurring billing charges.

We’re going to employ a resource with a few configurable parameters. Resource families have different configurable parameters.

1
2
3
4
5
6
7


export \
	USER_RESOURCE_SECTOR="us-stocks" \
	USER_RESOURCE_EXCHANGE=null \
	USER_RESOURCE_PRODUCT=null \
	USER_RESOURCE_ALLOCATION=70 \
	USER_RESOURCE_CONFIG_FREQUENCY=hourly \
 	USER_RESOURCE_CONFIG_MAX_SIZE=100

Variable	Description
`USER_RESOURCE_SECTOR`	One or more financial sectors to which the resource is being deployed to
`USER_RESOURCE_EXCHANGE`	A specific financial exchange the resource will read data from and submit orders to
`USER_RESOURCE_PRODUCT`	An array of products(tickers/symbols) to be used
`USER_RESOURCE_ALLOCATION`	A percentage of the user’s account size to be allocated to the resource; i.e., “allocate 20% of my account size to this portfolio manager.”
`USER_RESOURCE_CONFIG_FREQUENCY`	How frequently the resource can take actions; e.g., rebalance, adjust positions, place and cancel orders.
`USER_RESOURCE_CONFIG_MAX_SIZE`	The largest possible order size that the resource may submit.

Note: the resource’s balance may increase or decrease in percentage terms as it relates to the original account balance. As a result, you may experience significant “drift” from the original percentage allocation to the current time’s present allocation.
Note: the more frequent the data, the more potential actions, and the more potential trading costs.
Note: observe that a resource may place multiple orders over sequential time-steps resulting in a “total lot size” greater than max_size

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


curl -X \
  --request POST \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/resource/employ/manager/simple-manager" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data '{
  	"sector": "${USER_RESOURCE_SECTOR}",
    "exchange": "${USER_RESOURCE_EXCHANGE}",
    "product": "${USER_RESOURCE_PRODUCT}",
    "allocation": "${USER_RESOURCE_ALLOCATION}",
    "config": {
    	"frequency": "${USER_RESOURCE_CONFIG_FREQUENCY}",
    	"max_size": "${USER_RESOURCE_CONFIG_MAX_SIZE}"
    }
  }'

After employing the resource, you should receive a status message:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[
  {
    "timestamp": "2020-11-21T20:27:11.826252+00:00",
    "family": "manager",
    "name": "simple-manager",
    "id": "02348147-99b0-4a8c-b170-fa769f61dbb0",
    "status": 4,
    "session_id": "93fa3b6e-fd37-401c-b1c3-46be728e04ec",
    "portfolio_id" "7dc9f025-2c98-4cfc-9bcd-886864ad36f"
  }
]

1

"Unauthorized access - Unauthorized - you do not have access to this API"

Verify resource status

To check on the status of the resource, query the /resource/ping endpoint

1
2
3
4
5


curl -X \
  --request GET \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/resource/ping" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[
  {
    "timestamp": "2020-11-21T20:28:11.826252+00:00",
    "family": "manager",
    "name": "simple-manager",
    "id": "02348147-99b0-4a8c-b170-fa769f61dbb0",
    "status": 1,
    "session_id": "93fa3b6e-fd37-401c-b1c3-46be728e04ec",
    "portfolio_id" "7dc9f025-2c98-4cfc-9bcd-886864ad36f"
  }
]

export USER_RESOURCE_ID="02348147-99b0-4a8c-b170-fa769f61dbb0"

1

"Unauthorized access - Unauthorized - you do not have access to this API"

Retire a resource

You’ll probably want to shutdown your resource after awhile. Let’s send a POST request to the resource/retire endpoint and teardown our running resource.

You’ll need the USER_RESOURCE_ID environment variable from above.

1
2
3
4
5


curl -X \
  --request POST \
  --url "https://alpha.api.pocket-portfolio.com/resource/retire/${USER_RESOURCE_ID}" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should then see something like the below. (it may take a moment for the resource to properly cleanup and shutdown)

1

"400: User {###} did not return any registered resources. Are you sure this user registered a resource on this server?"

1

"Unauthorized access - Unauthorized - you do not have access to this API"

👍 Zvinoshamisa! You’ve employed and retired your first AI onto the Pocket Cloud!

1.7 - Check on your resource

Check-in on what your resource has been up to

Resources may generate actions which are then stored on the Pocket Cloud. These actions may result in orders being sent to financial exchanges which in turn may become transactions, affecting the user’s running ledger (if not in sandbox mode).

For example, the below user resource may generate the below action, resulting in two orders with an accompanying transaction and a linked resource reward.

graph LR
	U[User] --> UR([User Resource])

    UR([User Resource]) --> RA[Resource Action]

    RA[Resource Action] --> O1[Order 1]
    RA[Resource Action] --> O2[Order 2]

    O1[Order 1] --> T11[Transaction 1]

    O2[Order 2] --> T21[Transaction 2]
    O2[Order 2] --> T22[Transaction 3]

    RA[Resource Action] --> RR([Resource Reward])

Use SSE to receive up-to-date information from your resources

All of the below endpoints alternatively support the SSE protocol. You may open a long-lived session to the Pocket Cloud by passing the Accept: text/event-stream header to your HTTPs request. All other parameters remain the same.

Inspect resource records

Dependent on the type of resource, resources may output records from one or more actions. Records contain a historical record of the information a resource used to take an action. These actions can be inspected by querying the /object/record endpoint.

1
2
3
4
5
6


curl -X \
  --request GET \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/object/record" \
  --data '{"account_id": "${USER_ACCOUNT_ID}"}' \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

1
2
3
4
5
6
7


curl -X \
  --no-buffer \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/object/record" \
  --data '{"account_id": "${USER_ACCOUNT_ID}"}' \
  --header "Content-Type: text/event-stream" \
  --header "Accept: text/event-stream" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should see one of the below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
	"record_id": "d96bac1d-6b68-40d7-8f20-4d9d4f2e45fb",
	"session_id": "85aded01-2ce8-4955-947f-7030c1eb58b2",
	"user_id": "d6e729fa0bf5",
	"layer": ["SNAP"],
	"channel": ["NYSE American"],
	"logits": [0.561, 0.251, 0.952],
	"marked_by_soure_timestamp": [],
	"received_by_client_timestamp": [],
	"finished_by_pipeline_timestamp": [],
	"created_on_time": "2021-02-18 20:27:59.042804+00:00",
	"index": 98402018495,
	"finished_on_time": "2021-02-18 20:27:59.042824+00:00",
	"feedback_on_time": null,
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


data: {"type": "begin", "timestamp": "2021-02-18T19:55:17.774130"}

data: {
  "user_id": "${USER_USER_ID}",
  "session_id": "85aded01-2ce8-4955-947f-7030c1eb58b2",
  "name": "simple-manager",
  "record_id": "d96bac1d-6b68-40d7-8f20-4d9d4f2e45fb",
  "layer": ["SNAP"],
  "channel": ["NYSE American"],
  "logits": [0.561, 0.251, 0.952],
  "marked_by_source_timestamp": [],
  "received_by_client_timestamp": [],
  "finished_by_pipeline_timestamp": [],
  "created_on_time": "2021-02-18 20:27:59.042804+00:00",
  "finished_on_time": "2021-02-18 20:27:59.042824+00:00",
  "feedback_on_time": null,
  "index": [98402018495]
}

data: {...}

data: {"type": "end", "timestamp": "2021-02-18T19:55:17.774130"}

1

"You do not have access to this API"

1

"Could not find account - `account_id` not found"

When a resource takes an action, those actions are recorded under the record endpoint. For example, the above response yields actions for the SNAP ticker destined for the NYSE American exchange. These records may result in orders (below).

Inspect resource orders

Once a resource generates an action, that action may become one or more orders . Orders are submitted to either an explicitly defined exchange or an optimally chosen one. These actions may be inspected by querying the /object/order endpoint.

1
2
3
4
5
6


curl -X \
  --request GET \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/object/order" \
  --data '{"account_id": "${USER_ACCOUNT_ID}"}' \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

1
2
3
4
5
6
7


curl -X \
  --no-buffer \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/object/order" \
  --data '{"account_id": "${USER_ACCOUNT_ID}"}' \
  --header "Content-Type: text/event-stream" \
  --header "Accept: text/event-stream" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should see one of the below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


[
  {
    "parent_account_id": null,
    "account_id": "6ac0edf2-340b-48d4-87c1-36bcb033d7c1",
    "portfolio_id": "a6de702c-94c5-4183-a494-0a9fbe897e5c",
    "session_id": "85aded01-2ce8-4955-947f-7030c1eb58b2",
    "user_parent_oid": null,
    "user_oid": "8e5e7992-1fcb-4ed5-9158-4533f35cd33c",
    "exchange_oid": "bb41-2011eb6b70dc",
    "quantity": 97.56
    "side": 1,
    "status": -3,
    "price": 345.1,
    "fees": 45,
    "timestamp": "2021-11-14T01:34:26+00:12",
    "executions": [[10, 345.12], [87.56, 345.11]]
	},
	...
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


data: {"type": "begin", "timestamp": "2021-02-18T19:55:17.774130"}

data: {
  "parent_account_id": null,
  "account_id": "6ac0edf2-340b-48d4-87c1-36bcb033d7c1",
  "portfolio_id": "a6de702c-94c5-4183-a494-0a9fbe897e5c",
  "session_id": "85aded01-2ce8-4955-947f-7030c1eb58b2",
  "user_parent_oid": null,
  "user_oid": "8e5e7992-1fcb-4ed5-9158-4533f35cd33c",
  "exchange_oid": "bb41-2011eb6b70dc",
  "quantity": 97.56
  "side": 1,
  "status": -3,
  "price": 345.1,
  "fees": 45,
  "timestamp": "2021-11-14T01:34:26+00:12",
  "executions": [[10, 345.12], [87.56, 345.11]]
}

data: {...}

data: {"type": "end", "timestamp": "2021-02-18T19:55:17.774130"}

1

"You do not have access to this API"

1

"Could not find account - `account_id` not found"

Inspect resource rewards

The results of actions will output rewards , a feedback mechanism for informing the resource the status of its actions.

1
2
3
4
5
6


curl -X \
  --request GET \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/object/reward" \
  --data '{"account_id": "${USER_ACCOUNT_ID}"}' \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

1
2
3
4
5
6
7


curl -X \
  --no-buffer \
  --url "https://sandbox.alpha.api.pocket-portfolio.com/object/reward" \
  --data '{"account_id": "${USER_ACCOUNT_ID}"}' \
  --header "Content-Type: text/event-stream" \
  --header "Accept: text/event-stream" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"

You should see one of the below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[
   {
    "reward_id": "2d882b36-33b8-4ea2-a49d-9b1e564fa2cc",
    "session_id": "85aded01-2ce8-4955-947f-7030c1eb58b2",
    "user_id": "d6e729fa0bf5",
    "account_id": "4355bfdc-5b0c-49b8-9586-6cbff6c21f44",
    "layer": ["SNAP"],
    "channel": ["NYSE American"],
    "timestamp": "2021-11-14T01:34:26+00:12",
    "reward": 96,
  },
  ...
]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


data: {"type": "begin", "timestamp": "2021-02-18T19:55:17.774130"}

data:    {
  "reward_id": "2d882b36-33b8-4ea2-a49d-9b1e564fa2cc",
  "session_id": "85aded01-2ce8-4955-947f-7030c1eb58b2",
  "user_id": "d6e729fa0bf5",
  "account_id": "4355bfdc-5b0c-49b8-9586-6cbff6c21f44",
  "layer": ["SNAP"],
  "channel": ["NYSE American"],
  "timestamp": "2021-11-14T01:34:26+00:12",
  "reward": 96,
}

data: {...}

data: {"type": "end", "timestamp": "2021-02-18T19:55:17.774130"}

1

"You do not have access to this API"

1

"Could not find account - `account_id` not found"

Resource actions will affect your portfolio and account state. Let’s inspect our linked account ledger to determine what all has occurred.

Inspect ledger state

Accounts and portfolios are linked to ledgers , a running financial statement of your resource’s actions. In free and personal mode, each account has one running ledger.

1

@TODO

1

@TODO

You should see one of the below:

1

@TODO

1

@TODO

1

"You do not have access to this API"

1

"Could not find account - `account_id` not found"

👍 Meravellós! You’ve checked-in on the state of your AI on the Pocket Cloud!

Tutorials

1 - Getting Started

Learning Outcomes

1.1 - Create a new user

Create a new user

Only free and personal accounts are supported!

Generate an access token

Not the most secure option!

1.2 - Access the user account

Access user account

Check account status:

Account is not yet verified!

Get account details:

1.3 - Verify the user entity

Verify user entity

Kick-off verification

Check verification status

1.4 - Fund your account

1.5 - Create a portfolio

Create a portfolio

1.6 - Deploy a resource

Employ a resource

Verify resource status

Retire a resource

1.7 - Check on your resource

Use SSE to receive up-to-date information from your resources

Inspect resource records

Inspect resource orders

Inspect resource rewards

Inspect ledger state

1.8 -