Planbok V2 API

Wallets

Endpoint

Create wallets

POST

https://api.planbok.io

/v2/organization/wallets

Creates new wallets within an organization.

Create wallets › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Create wallets › Request Body

idempotencyKey

string · uuid · required

A unique UUID v4 to ensure request idempotency.

blockchains

string[] · required

The blockchain(s) for which to create wallets.

Enum values:

ARB

ARB-SEPOLIA

AVAX-C

AVAX-C-FUJI

BASE

BASE-SEPOLIA

BSC

BSC-TESTNET

walletSetId

string · required

The ID of the wallet set to which the wallets will be added.

object[] · required

A list of metadata fields to link with the wallet. Ensure the number of items in this array matches the count value exactly.

count

integer

The number of wallets to create per blockchain.

Default: 1

accountType

string · enum

The type of account to create, default is eoa. Smart Contract Accounts (SCA) are coming soon.

Enum values:

eoa

sca

Default: eoa

encryptedOrganizationSecret

string

Required only for organizations operating in trustless MPC mode. Must be a base64 encoded ciphertext.

Create wallets › Responses

Wallets created

success

boolean

status

integer

message

string

object

POST/v2/organization/wallets

curl --request POST \
  --url https://api.planbok.io/v2/organization/wallets \
  --header 'Content-Type: application/json' \
  --header 'PLANBOK-X-API-KEY: <string>' \
  --data '
{
  "idempotencyKey": "123e4567-e89b-12d3-a456-426614174010",
  "blockchains": [
    "ETH-SEPOLIA",
    "SOL-TESTNET",
    "BTC-TESTNET",
    "NEAR-TESTNET"
  ],
  "walletSetId": "69a294c82370a778f3fbccfc",
  "count": 2,
  "metadata": [
    {
      "name": "ifeanyi",
      "refId": "user_0"
    },
    {
      "name": "ogechi",
      "refId": "user_1"
    }
  ],
  "accountType": "eoa",
  "encryptedOrganizationSecret": ""
}
'

shell

Example Request Body

{
  "idempotencyKey": "123e4567-e89b-12d3-a456-426614174010",
  "blockchains": [
    "ETH-SEPOLIA",
    "SOL-TESTNET",
    "BTC-TESTNET",
    "NEAR-TESTNET"
  ],
  "walletSetId": "69a294c82370a778f3fbccfc",
  "count": 2,
  "metadata": [
    {
      "name": "ifeanyi",
      "refId": "user_0"
    },
    {
      "name": "ogechi",
      "refId": "user_1"
    }
  ],
  "accountType": "eoa",
  "encryptedOrganizationSecret": ""
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "wallets": [
      {
        "id": "69a2f6c2a80a22691f80f868",
        "name": "ifeanyi",
        "refId": "user_0",
        "blockchain": "ETH-SEPOLIA",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f67da80a22691f80f85d",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "0xbba521dfce426f5b77096d440d7199c1503d1f9d",
        "publicKey": "036a822324b18f62617c29908514e876700e7a6c800c5269d3d3dc2d05c18aa14d"
      },
      {
        "id": "69a2f6c2a80a22691f80f875",
        "name": "ifeanyi",
        "refId": "user_0",
        "blockchain": "SOL-TESTNET",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f67da80a22691f80f85d",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "9E7NoEHhdocgo4zY1DbB3tb1HioCNzdqHvSHSAenkdJ3",
        "publicKey": "7a39414d06b8a3e569b0c3cd1f855bff4705564cb5493d83f3969bed52a1ba54"
      },
      {
        "id": "69a2f6c2a80a22691f80f881",
        "name": "ifeanyi",
        "refId": "user_0",
        "blockchain": "BTC-TESTNET",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f67da80a22691f80f85d",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "tb1q4l22l3aeznjaz8twv62tlxfv8c6fehr6l2e2fc",
        "publicKey": "020624bfc0ed12a12d11341f9fdea84671bea907f3a14c6a97329e9523bbe63fc9"
      },
      {
        "id": "69a2f6c2a80a22691f80f88d",
        "name": "ifeanyi",
        "refId": "user_0",
        "blockchain": "NEAR-TESTNET",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f67da80a22691f80f85d",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "01b1a7c4e325d574e24829fb2343c35fc9e9b139b2b2ec1d2ea345f6893c7f08",
        "publicKey": "01b1a7c4e325d574e24829fb2343c35fc9e9b139b2b2ec1d2ea345f6893c7f08"
      },
      {
        "id": "69a2f6c3a80a22691f80f89e",
        "name": "ogechi",
        "refId": "user_1",
        "blockchain": "ETH-SEPOLIA",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f6c2a80a22691f80f89b",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "0x5e6fd3632820786d68b64c513b34fe7c9606375b",
        "publicKey": "02cd6f9bbb0b070de780c7896f2a4fdcf62b3a3bc1148ccfba37ffdf1b73ba4e8c"
      },
      {
        "id": "69a2f6c3a80a22691f80f8a3",
        "name": "ogechi",
        "refId": "user_1",
        "blockchain": "SOL-TESTNET",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f6c2a80a22691f80f89b",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "6uiVr2ZijUSS7aEnf98yLvAgQEBR9MrC8W4gVSMgdq7y",
        "publicKey": "57cb8ed1b2ffb5a8b240a429623cf623045f10a31790196ce281cd7eebb68724"
      },
      {
        "id": "69a2f6c3a80a22691f80f8a8",
        "name": "ogechi",
        "refId": "user_1",
        "blockchain": "BTC-TESTNET",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f6c2a80a22691f80f89b",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "tb1qd77jtaxue8zt27wpm3fn9h8q9x26ppq3y9m75k",
        "publicKey": "02714be588c922d020c9e6e7aa40b71581a1fb2f5fe44791b3c30ed5b4d6e3d60c"
      },
      {
        "id": "69a2f6c3a80a22691f80f8ad",
        "name": "ogechi",
        "refId": "user_1",
        "blockchain": "NEAR-TESTNET",
        "controller": "organization",
        "state": "active",
        "organization": "69a1f47b0993b0d19f40e73c",
        "customer": "69a2f6c2a80a22691f80f89b",
        "walletSet": "69a294c82370a778f3fbccfc",
        "type": "eoa",
        "address": "b076f5e59522964c813045f7f32f276b66b33c97770e59ee74655d8f3adf3d7b",
        "publicKey": "b076f5e59522964c813045f7f32f276b66b33c97770e59ee74655d8f3adf3d7b"
      }
    ]
  },
  "message": "Wallets created",
  "status": 201
}

json

application/json

Update Wallet Metadata

PUT

https://api.planbok.io

/v2/organization/wallets/{id}

Updates the name or refId of a wallet.

Update Wallet Metadata › path Parameters

id

string · required

Wallet ID

Update Wallet Metadata › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Update Wallet Metadata › Request Body

object

Update Wallet Metadata › Responses

200

Wallet updated successfully

success

boolean

status

integer

message

string

object

PUT/v2/organization/wallets/{id}

curl --request PUT \
  --url https://api.planbok.io/v2/organization/wallets/:id \
  --header 'Content-Type: application/json' \
  --header 'PLANBOK-X-API-KEY: <string>' \
  --data '
{
  "metadata": {
    "name": "welechi",
    "refId": "user_001"
  }
}
'

shell

Example Request Body

{
  "metadata": {
    "name": "welechi",
    "refId": "user_001"
  }
}

json

application/json

Example Responses

{
  "success": true,
  "data": {
    "id": "69a2f6c2a80a22691f80f881",
    "name": "welechi",
    "refId": "user_001",
    "blockchain": "BTC-TESTNET",
    "controller": "organization",
    "state": "active",
    "organization": "69a1f47b0993b0d19f40e73c",
    "customer": "69a2f67da80a22691f80f85d",
    "walletSet": "69a294c82370a778f3fbccfc",
    "type": "eoa",
    "address": "tb1q4l22l3aeznjaz8twv62tlxfv8c6fehr6l2e2fc",
    "publicKey": "020624bfc0ed12a12d11341f9fdea84671bea907f3a14c6a97329e9523bbe63fc9"
  },
  "message": "Wallet updated",
  "status": 200
}

json

application/json

List Wallets

GET

https://api.planbok.io

/v2/wallets

Returns a list of wallets for the organization or customer.

List Wallets › query Parameters

blockchain

string · enum

The blockchain identifier.

Enum values:

ARB

ARB-SEPOLIA

AVAX-C

AVAX-C-FUJI

BASE

BASE-SEPOLIA

BSC

BSC-TESTNET

customerIds

string

Comma separated list of customer IDs

walletSet

string

ID of the wallet set

refId

string

Reference ID of the wallet

address

string

Address of the wallet

page

integer

Default: 1

limit

integer

Default: 10

order

string · enum

Enum values:

asc

desc

Default: desc

List Wallets › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List Wallets › Responses

200

List of wallets

success

boolean

status

integer

object

message

string

object[]

GET/v2/wallets

curl --request GET \
  --url https://api.planbok.io/v2/wallets \
  --header 'PLANBOK-X-API-KEY: <string>'

shell

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "69a2f6c3a80a22691f80f8ad",
      "name": "ogechi",
      "refId": "user_1",
      "blockchain": "NEAR-TESTNET",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f6c2a80a22691f80f89b",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "b076f5e59522964c813045f7f32f276b66b33c97770e59ee74655d8f3adf3d7b",
      "publicKey": "b076f5e59522964c813045f7f32f276b66b33c97770e59ee74655d8f3adf3d7b"
    },
    {
      "id": "69a2f6c3a80a22691f80f8a8",
      "name": "ogechi",
      "refId": "user_1",
      "blockchain": "BTC-TESTNET",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f6c2a80a22691f80f89b",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "tb1qd77jtaxue8zt27wpm3fn9h8q9x26ppq3y9m75k",
      "publicKey": "02714be588c922d020c9e6e7aa40b71581a1fb2f5fe44791b3c30ed5b4d6e3d60c"
    },
    {
      "id": "69a2f6c3a80a22691f80f8a3",
      "name": "ogechi",
      "refId": "user_1",
      "blockchain": "SOL-TESTNET",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f6c2a80a22691f80f89b",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "6uiVr2ZijUSS7aEnf98yLvAgQEBR9MrC8W4gVSMgdq7y",
      "publicKey": "57cb8ed1b2ffb5a8b240a429623cf623045f10a31790196ce281cd7eebb68724"
    },
    {
      "id": "69a2f6c3a80a22691f80f89e",
      "name": "ogechi",
      "refId": "user_1",
      "blockchain": "ETH-SEPOLIA",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f6c2a80a22691f80f89b",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "0x5e6fd3632820786d68b64c513b34fe7c9606375b",
      "publicKey": "02cd6f9bbb0b070de780c7896f2a4fdcf62b3a3bc1148ccfba37ffdf1b73ba4e8c"
    },
    {
      "id": "69a2f6c2a80a22691f80f88d",
      "name": "ifeanyi",
      "refId": "user_0",
      "blockchain": "NEAR-TESTNET",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f67da80a22691f80f85d",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "01b1a7c4e325d574e24829fb2343c35fc9e9b139b2b2ec1d2ea345f6893c7f08",
      "publicKey": "01b1a7c4e325d574e24829fb2343c35fc9e9b139b2b2ec1d2ea345f6893c7f08"
    },
    {
      "id": "69a2f6c2a80a22691f80f881",
      "name": "welechi",
      "refId": "user_001",
      "blockchain": "BTC-TESTNET",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f67da80a22691f80f85d",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "tb1q4l22l3aeznjaz8twv62tlxfv8c6fehr6l2e2fc",
      "publicKey": "020624bfc0ed12a12d11341f9fdea84671bea907f3a14c6a97329e9523bbe63fc9"
    },
    {
      "id": "69a2f6c2a80a22691f80f875",
      "name": "welechi",
      "refId": "user_001",
      "blockchain": "SOL-TESTNET",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f67da80a22691f80f85d",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "9E7NoEHhdocgo4zY1DbB3tb1HioCNzdqHvSHSAenkdJ3",
      "publicKey": "7a39414d06b8a3e569b0c3cd1f855bff4705564cb5493d83f3969bed52a1ba54"
    },
    {
      "id": "69a2f6c2a80a22691f80f868",
      "name": "ifeanyi",
      "refId": "user_0",
      "blockchain": "ETH-SEPOLIA",
      "controller": "organization",
      "state": "active",
      "organization": "69a1f47b0993b0d19f40e73c",
      "customer": "69a2f67da80a22691f80f85d",
      "walletSet": "69a294c82370a778f3fbccfc",
      "type": "eoa",
      "address": "0xbba521dfce426f5b77096d440d7199c1503d1f9d",
      "publicKey": "036a822324b18f62617c29908514e876700e7a6c800c5269d3d3dc2d05c18aa14d"
    }
  ],
  "message": "Wallets retrieved",
  "pagination": {
    "total": 8,
    "page": 1,
    "pages": 1
  },
  "status": 200
}

json

application/json

Get Wallet Details

GET

https://api.planbok.io

/v2/wallets/{id}

Returns details for a specific wallet.

Get Wallet Details › path Parameters

id

string · required

Wallet ID

Get Wallet Details › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get Wallet Details › Responses

200

Wallet details

success

boolean

status

integer

message

string

object

List Token Balances

GET

https://api.planbok.io

/v2/wallets/{id}/balances

Returns the token balances for a specific wallet.

List Token Balances › path Parameters

id

string · required

Wallet ID

List Token Balances › query Parameters

page

integer

Default: 1

limit

integer

Default: 10

order

string · enum

Enum values:

asc

desc

Default: desc

List Token Balances › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List Token Balances › Responses

200

Token balances retrieved

success

boolean

status

integer

object

message

string

object[]

Validate Blockchain Address

POST

https://api.planbok.io

/v2/wallets/validate-address

Validates if an address is syntactically correct for a specific blockchain.

Validate Blockchain Address › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Validate Blockchain Address › Request Body

blockchain

string · enum · required

The blockchain identifier.

Enum values:

ARB

ARB-SEPOLIA

AVAX-C

AVAX-C-FUJI

BASE

BASE-SEPOLIA

BSC

BSC-TESTNET

address

string · required

Validate Blockchain Address › Responses

200

Address validation result

success

boolean

status

integer

message

string

object

Wallet Sets Tokens

Create wallets

POST

https://api.planbok.io

/v2/organization/wallets

Creates new wallets within an organization.

Create wallets › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Create wallets › Request Body

idempotencyKey

string · uuid · required

A unique UUID v4 to ensure request idempotency.

blockchains

string[] · required

The blockchain(s) for which to create wallets.

Enum values:

ARB

ARB-SEPOLIA

AVAX-C

AVAX-C-FUJI

BASE

BASE-SEPOLIA

BSC

BSC-TESTNET

walletSetId

string · required

The ID of the wallet set to which the wallets will be added.

object[] · required

A list of metadata fields to link with the wallet. Ensure the number of items in this array matches the count value exactly.

count

integer

The number of wallets to create per blockchain.

Default: 1

accountType

string · enum

The type of account to create, default is eoa. Smart Contract Accounts (SCA) are coming soon.

Enum values:

eoa

sca

Default: eoa

encryptedOrganizationSecret

string

Required only for organizations operating in trustless MPC mode. Must be a base64 encoded ciphertext.

Create wallets › Responses

Wallets created

success

boolean

status

integer

message

string

object

Update Wallet Metadata

PUT

https://api.planbok.io

/v2/organization/wallets/{id}

Updates the name or refId of a wallet.

Update Wallet Metadata › path Parameters

id

string · required

Wallet ID

Update Wallet Metadata › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Update Wallet Metadata › Request Body

object

Update Wallet Metadata › Responses

200

Wallet updated successfully

success

boolean

status

integer

message

string

object

List Wallets

GET

https://api.planbok.io

/v2/wallets

Returns a list of wallets for the organization or customer.

List Wallets › query Parameters

blockchain

string · enum

The blockchain identifier.

Enum values:

ARB

ARB-SEPOLIA

AVAX-C

AVAX-C-FUJI

BASE

BASE-SEPOLIA

BSC

BSC-TESTNET

customerIds

string

Comma separated list of customer IDs

walletSet

string

ID of the wallet set

refId

string

Reference ID of the wallet

address

string

Address of the wallet

page

integer

Default: 1

limit

integer

Default: 10

order

string · enum

Enum values:

asc

desc

Default: desc

List Wallets › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List Wallets › Responses

200

List of wallets

success

boolean

status

integer

object

message

string

object[]

Get Wallet Details

GET

https://api.planbok.io

/v2/wallets/{id}

Returns details for a specific wallet.

Get Wallet Details › path Parameters

id

string · required

Wallet ID

Get Wallet Details › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Get Wallet Details › Responses

200

Wallet details

success

boolean

status

integer

message

string

object

List Token Balances

GET

https://api.planbok.io

/v2/wallets/{id}/balances

Returns the token balances for a specific wallet.

List Token Balances › path Parameters

id

string · required

Wallet ID

List Token Balances › query Parameters

page

integer

Default: 1

limit

integer

Default: 10

order

string · enum

Enum values:

asc

desc

Default: desc

List Token Balances › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

List Token Balances › Responses

200

Token balances retrieved

success

boolean

status

integer

object

message

string

object[]

Validate Blockchain Address

POST

https://api.planbok.io

/v2/wallets/validate-address

Validates if an address is syntactically correct for a specific blockchain.

Validate Blockchain Address › Headers

PLANBOK-X-API-KEY

string · required

API key for authentication

Validate Blockchain Address › Request Body

blockchain

string · enum · required

The blockchain identifier.

Enum values:

ARB

ARB-SEPOLIA

AVAX-C

AVAX-C-FUJI

BASE

BASE-SEPOLIA

BSC

BSC-TESTNET

address

string · required

Validate Blockchain Address › Responses

200

Address validation result

success

boolean

status

integer

message

string

object