Players

On this page, we'll dive into the different player endpoints you can use to manage players programmatically. We'll look at how to create, read, update and delete players.

Endpoints

GET /v1/playersPOST /v1/playersPOST /v1/players/:id/sessionGET /v1/players/:idPOST /v1/players/:idPOST /v1/players/:id/transfer-ownershipGET /v1/players/:id/accounts

The Player object

Attributes

Name
id
Type
string
Description
This is the ID of the player. It starts with pla_.
Name
name
Type
string
Description
The name for the player.
Name
description
Type
string
Description
An arbitrary string that you can attach to a player object. It is displayed alongside the player in the dashboard.
Name
created_at
Type
timestamp
Description
A timestamp representing the date and time that the player was created.
Name
email
Type
string
Description
A string representing the player's email address.
Name
metadata
Type
hash
Description
Additional metadata associated with the player.
Name
accounts
Type
array of hashes (expandable)
Description
A list of accounts associated with the player. Refer to Accounts object.
This can be expanded into an object with the expand request parameter.
Name
transaction_intents
Type
array of hashes (expandable)
Description
A list of accounts associated with the player. Refer to Transaction Intents object.
This can be expanded into an object with the expand request parameter.

More attributes

GET/v1/players

List all players

This endpoint allows you to retrieve a paginated list of all your players. By default, a maximum of ten players are shown per page.

Expandable Example

Notice that, in the example, the player in the list have two accounts (objects starting with acc...). To retrieve them in one call, just add -d "expand[]=accounts" to the command. This will fetch the information of all players and their related accounts. For more information about how expand works, refer to Expanding Responses.

Request

GET

/v1/players

  curl -G https://api.openfort.xyz/v1/players \
  -H "Authorization: Bearer $YOUR_SECRET_KEY"

Response

  {
    "object": "list",
    "url": "/v1/players",
    "data": [
      {
        "id": "pla_...",
        "object": "player",
        "created_at": "2023-04-08T11:19:20.897Z",
        "name": "Frank McCallister",
        "email": "Frank@dMcCallister.com",
        "description": "Tutorial",
        "livemode": false,
        "metadata": null,
        "accounts": [
          "acc_...",
          "acc_..."
        ],
        "transaction_intents": [
          "tin_..."
        ]
      },
      {
        "id": "pla_...",
        "object": "player",
        ...
      }
    ]
    ...
  }

POST/v1/players

Create a player

This endpoint allows you to add a new player to your player list in Openfort. To add a player, you must provide their Openfort username.

Required attributes

Name
name
Type
string
Description
The name for the player.

Optional attributes

Name
description
Type
string
Description
An arbitrary string that you can attach to a player object. It is displayed alongside the player in the dashboard.

Request

POST

/v1/players

  curl https://api.openfort.xyz/v1/players \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d name="FrankMcCallister" \
  -d description="My First Test Player (created for API docs at https://www.openfort.xyz/docs/api)"

Response

  {
    "id": "pla_...",
    "created_at": "2023-04-03T12:37:46.580Z",
    "name": "FrankMcCallister",
    "email": null,
    "description": "My First Test Player (created for API docs at https://www.openfort.xyz/docs/api)",
    "livemode": false,
    "metadata": null,
    "object": "player"
  }

POST/v1/players/:id/session

Register a player session

This endpoint is used for the registration of new session keys for a given player. The player can be using a non-custodial account or a custodial account.

Notice that the responses are also quite different for players using non-custodial accounts from players using custodial accounts. Non-custodial accounts have the next_action value filled with information that the owner needs to sign and send in a subsequent API request to authorize the registration of the session key.

Required attributes

Name
address
Type
string
Description
A string representing the session key's address.
Name
valid_after
Type
timestamp
Description
A 6-byte timestamp representing the number of seconds elapsed since midnight on January 1, 1970. The session key is valid only up to this time. The minimum value is 0 and the maximum is 281474976710655.
Name
valid_until
Type
timestamp
Description
A 6-byte timestamp representing the number of seconds elapsed since midnight on January 1, 1970. The session key is valid only after this time. The minimum value is 0 and the maximum is 281474976710655.

Optional attributes

Name
policy
Type
string
Description
The unique identifier for the gas policy to be used for this transaction. It starts with pol_.
Name
external_owner_address
Type
string
Description
If an account doesn't exist for the specified chain_id and player, the external_owner_address is used as the owner of the new account that will be created.
Name
whitelist
Type
array of strings
Description
Array of addresses that the session key has permission to interact with. When not provided, session key can interact with any address.
Name
limit
Type
int
Description
Number of times that the given session key can be used. Default is 100.

Request

POST

/v1/players/:id/session

  curl https://api.openfort.xyz/v1/players/pla_.../session \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d address=0x76e6...9341 \
  -d valid_after=0 \
  -d valid_until=281474976710655 \
  -d policy=pol_... \
  -d whitelist[0]=0x8a16...CE4a

Response (custodial)

  {
    "id": "ses_...",
    "created_at": "2023-04-25T16:35:11.013Z",
    "valid_after": "1650000000",
    "valid_until": "1700000000",
    "whitelist": [],
    "limit": 100,
    "next_action": null,
    "object": "session"
  }

GET/v1/players/:id

Retrieve a player

This endpoint allows you to retrieve a player by providing their Openfort player id.

Request

GET

/v1/players/:id

  curl -G https://api.openfort.xyz/v1/players/pla_... \
  -H "Authorization: Bearer $YOUR_SECRET_KEY"

Response

  {
    "id": "pla_...",
    "created_at": "2023-04-06T21:14:06.646Z",
    "livemode": false,
    "email": null,
    "description": "tutorial account",
    "metadata": null,
    "name": "Frank McCallister",
    "object": "player",
    "accounts": [
        {
            "id": "acc_bf851d08-dac0-478d-b7b8-887c37e9b568",
            "created_at": "2023-04-06T21:14:12.063Z",
            "address": "0x63B7dCD88658f0609adDac08Cfae6538f084484f",
            "chain_id": 5,
            "deployed": false,
            "object": "account",
            ...
        }
    ],
  }

POST/v1/players/:id

Update a player

This endpoint allows you to perform an update on a player. Currently, the only attribute that can be updated on players is the name and description attribute which controls how a player appears in your player list in Openfort.

Optional attributes

Name
name
Type
string
Description
The player display name in the player list. By default, this is just the username.
Name
description
Type
string
Description
An arbitrary string that you can attach to a player object. It is displayed alongside the player in the dashboard.

Request

POST

/v1/players/:id

  curl https://api.openfort.xyz/v1/players/pla_... \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d description="Updated description"

Response

  {
    "id": "pla_...",
    "created_at": "2023-04-07T17:34:13.227Z",
    "livemode": false,
    "email": null,
    "description": "Updated description",
    "metadata": null,
    "name": "mr.hames",
    "object": "player"
  }

POST/v1/players/:id/transfer-ownership

Transfer account ownership

This endpoint allows you to perform an update on the owner of an account of the player at the specified chain. To perfom an update on the owner of an account, first you must provide a new owner address. Then, the new owner must accept to take ownership by calling acceptOwnership() in the smart contract account.

Required attributes

Name
new_owner_address
Type
string
Description
A string representing the account's new owner address.
Name
chain_id
Type
int
Description
The ID of the blockchain network.

Optional attributes

Name
policy
Type
string
Description
The unique identifier for the gas policy to be used for this transaction. It starts with pol_.

Request

POST

/v1/players/:id/transfer-ownership

  curl https://api.openfort.xyz/v1/players/pla_.../transfer-ownership \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -d new_owner_address="0xe781...0185" \
  -d chain_id=5 \
  -d policy="pol_..."

Response

  {
    "id": "tin_...",
    "created_at": "2023-04-25T09:12:22.214Z",
    "user_operation_hash": "0x4165...d18f",
    "user_operation": {
        "sender": "0xc017dBca3F51E0655AbF1303B6054Cc4eed8A908",
        "nonce": 0,
        ...
    },
    "chain_id": 80001,
    "updated_at": "2023-04-25T09:12:22.214Z",
    "policy": "pol_...",
    "account": "acc_...",
    "next_action": null,
    "player": "pla_...",
    "response": {
        "created_at": "2023-04-25T09:12:40.941Z",
        ...
    },
    "transactions": [
        ...
    ],
    "object": "transaction_intent"
  }

GET/v1/players/:id/accounts

List a player's accounts

This endpoint allows you to retrieve a paginated list of all accounts of a player. By default, a maximum of ten accounts are shown per page.

Request

GET

/v1/players/:id/accounts

  curl -G https://api.openfort.xyz/v1/players/pla_.../accounts \
  -H "Authorization: Bearer $YOUR_SECRET_KEY"

Response

  {
    "object": "list",
    "url": "/v1/accounts",
    "data": [
      {
          "id": "acc_...",
          "created_at": "2023-04-04T09:17:45.102Z",
          "address": "0x868E...F765",
          "chain_id": 5,
          "deployed": false
      },
      {
          "id": "acc_..."
          // ...
      }
    ]
  }