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
ordestination
in transfers. - As the receiver wallet for payment links.
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 aCustomer
.merchant
: The wallet belongs to the merchant, i.e., at the level of theApplication
. Relevant for custodial wallets.bridge
: The wallet belongs to Bridge. Found in thefunding
bank account field of thetransfer
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
, andbase
. - Payment supported networks are
sol
,ethereum
,bitcoin
,polygon
,gnosis
,optimism
,arbitrum
,bsc
, andsepolia
. - Custodial wallet supported networks are
sol
,ethereum
, andoptimism
.
- Transfer supported networks are
- 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"
},
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
, andbase
. - Payment supported networks are
sol
,ethereum
,bitcoin
,polygon
,gnosis
,optimism
,arbitrum
,bsc
, andsepolia
. - Custodial wallet supported networks are
sol
,ethereum
, andoptimism
.
- Transfer supported networks are
- 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. Theowner
field will be set tomerchant
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
andmpk
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
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.
Retrieve a wallet
This endpoint allows you to retrieve a wallet by its id.
Request
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"
}