Wallets

The wallet object identifies where funds should be withdrawn or settled to on a given network.

You may create wallet objects for your customer before they have been approved for KYC/B or ToS.

Wallets have various uses, ranging from both transfers and payments:

As the source or destination in transfers.
As the receiver wallet for payment links.

Endpoints

The Wallet object

Properties

Name
id
Type
string
Description
A unique identifier for the object.
Name
address
Type
string
Description
The on-chain address of the wallet.
Name
risk
Type
string
Description
The risk score of the wallet.
Name
primary
Type
boolean
Description
Whether the wallet is the customer's primary wallet.
Name
feePayer
Type
boolean
Description
Whether the wallet is a fee payer.
Name
nickname
Type
string
Description
The nickname given to the wallet.
Name
customer
Type
string
Description
The id of the customer associated with the wallet.
Name
owner
Type
enum
Description
The owner of the wallet.
- customer: The wallet belongs to a Customer.
- merchant: The wallet belongs to the merchant, i.e., at the level of the Application. Relevant for custodial wallets.
- bridge: The wallet belongs to Bridge. Found in the funding bank account field of the transfer object.
Name
exported
Type
timestamp
Description
Datetime of when the wallet was exported, null if the wallet has not been exported.
Name
signed
Type
boolean
Description
Whther the user has signed a message with the wallet. Verifies that the user owns the wallet.
Name
network
Type
enum
Description
The wallet's network.
- Transfer supported networks are sol, ethereum, and base.
- Payment supported networks are sol, ethereum, bitcoin, polygon, gnosis, optimism, arbitrum, bsc, and sepolia.
- Custodial wallet supported networks are sol, ethereum, and optimism.
Name
mock
Type
boolean
Description
Whether the wallet is a mock wallet. False by default.
Name
lookupKey
Type
string
Description
The lookup key of a wallet. A lookup key allows you to list all resources associated with a given key.
Name
balance
Type
number
Description
The balance of the wallet in the base currency. Only used if the wallet is a bitcoin wallet.
Name
created
Type
timestamp
Description
Datetime of when the wallet was created.
Name
updated
Type
timestamp
Description
Datetime of when the wallet was last updated.
Name
deleted
Type
timestamp
Description
Datetime of when the wallet was deleted, null if the wallet has not been deleted.

Wallet Object

{
  "wallet": { 
    "id": "wallet_5d268f096b08486a843e30b23eb8fe09",
    "address": "BGkpRfK8L5Yy7A8wimA4CXra2GhFxdSWK944Ap6dPKCu",
    "network": "sol",
    "nickname": null,
    "risk": "Low",
    "primary": false,
    "feePayer": false,
    "signed": false,
    "mock": false,
    "customer": null,
    "owner": "customer",
    "exported": null,
    "created": "2024-08-04T07:21:39.021Z",
    "updated": "2024-08-04T07:21:39.021Z",
    "deleted": null
  },
  "ts": "2024-08-04T07:21:39.032Z",
  "request": "request_9193c3a3051947869130f94753178cd7"
},

POST/v1/wallet

Create a wallet

This endpoint allows you to create a new wallet.

Paremeter

Name
network
Type
enum
Required
Required
Description
The network of the wallet.
- Transfer supported networks are sol, ethereum, and base.
- Payment supported networks are sol, ethereum, bitcoin, polygon, gnosis, optimism, arbitrum, bsc, and sepolia.
- Custodial wallet supported networks are sol, ethereum, and optimism.
Name
address
Type
string
Required
Required
Description
The address of the wallet. Only required if custodial is false.
Name
customer
Type
string
Description
The id of the customer associated with the wallet. The owner field will be set to merchant if not provided.
Name
nickname
Type
string
Description
The nickname of the wallet.
Name
lookupKey
Type
string
Description
The lookup key of a wallet. A lookup key allows you to list all resources associated with a given key.
Name
mpk
Type
string
Description
The master public key of the wallet. Only relevant for bitcoin wallets.
Name
custodial
Type
boolean
Description
Whether the wallet is a custodial wallet or not. The address and mpk field should not be passed in if this field is true.
Name
feePayer
Type
boolean
Description
Whether the wallet is a fee payer or not. Only relevant for custodial wallets.

Request

POST

/v1/wallet

curl https://api.spherepay.co/v1/wallet \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{
    \"network\": \"sol\",
    \"address\": \"BTkpRfK8L5Yy7A8wimA4CXra2GhFxdSWK944Ap6dPKCu\"
  }"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "wallet": {
      "id": "wallet_78c2aff1f0ca4e3dacfab44c75c73147",
      "address": "BTkpRfK8L5Yy7A8wimA4CXra2GhFxdSWK944Ap6dPKCu",
      "network": "sol",
      "nickname": null,
      "risk": "Low",
      "primary": false,
      "feePayer": false,
      "signed": false,
      "mock": false,
      "lookupKey": null,
      "customer": null,
      "owner": "merchant",
      "exported": null,
      "created": "2024-08-08T23:22:59.419Z",
      "updated": "2024-08-08T23:22:59.419Z",
      "deleted": null
    }
  },
  "ts": "2024-08-13T12:57:10.943Z",
  "request": "request_ca22d5a3de42482393cd511d720d5944"
}

A note on creating wallets

The create wallet endpoint will create or retrieve wallets. That is, if the wallet does not exist, it will be created. If the wallet exists, it will be retrieved.

GET/v1/wallet/:id

Retrieve a wallet

This endpoint allows you to retrieve a wallet by its id.

Request

GET

/v1/wallet/:id

curl -G https://api.spherepay.co/v1/wallet/wallet_78c2aff1f0ca4e3dacfab44c75c73147 \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "wallet": {
      "id": "wallet_78c2aff1f0ca4e3dacfab44c75c73147",
      "address": "BTkpRfK8L5Yy7A8wimA4CXra2GhFxdSWK944Ap6dPKCu",
      "network": "sol",
      "nickname": null,
      "risk": "Low",
      "primary": false,
      "feePayer": false,
      "signed": false,
      "mock": false,
      "lookupKey": null,
      "customer": null,
      "owner": "merchant",
      "exported": null,
      "created": "2024-08-08T23:22:59.419Z",
      "updated": "2024-08-08T23:22:59.419Z",
      "deleted": null
    }
  },
  "ts": "2024-08-13T13:01:56.004Z",
  "request": "request_88b5f097870742e0887f6caeb6c2c69a"
}