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 payouts and payments:

As the source or destination in payouts.
As the receiver wallet for payment links.
As a custodial wallet to interact with either payouts or payment links.
As the source in the creation of bank wallets.

Endpoints

/v1/wallet/custodial/exportPrivateKey

POST

/v1/wallet/custodial/transfer

POST

/v1/wallet/custodial/solana/broadcast/versioned

The Wallet object

Properties

Name
id
Type
string
Description
Unique identifier for the wallet. Auto-generated by Sphere upon creation.
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 payout 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.
- Payout 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.
- Payout 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"
}

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"
}

POST/v1/wallet/custodial/exportPrivateKey

Export a custodial wallet

This endpoint allows you to export a custodial wallet. Once a custodial wallet is exported, it can no longer be used to sign or send transactions.

Paremeter

Name
walletId
Type
string
Required
Required
Description
The id of the wallet to export.
Name
disclaimer
Type
string
Required
Required
Description
The disclaimer text to display to the user.

Request

POST

/v1/wallet/custodial/exportPrivateKey

curl https://api.spherepay.co/v1/wallet/custodial/exportPrivateKey \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{
    \"walletId\": \"wallet_ba5a0059977f49faaeec27d0dc88500a\",
    \"disclaimer\": \"By exporting this wallet's private key, I am taking over full responsibility for its safety. This means Sphere will not be able to help if things go wrong and will stop support for signing and broadcasting transactions with this wallet. I understand that managing my private key comes with risks, like unauthorized access or loss of assets. I agree not to hold Sphere responsible for any issues that arise after I have exported my key. I am ready and equipped to keep my private key secure. My action to export signifies I understand and accept these conditions.\"
  }"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "walletId": "wallet_ba5a0059977f49faaeec27d0dc88500a",
    "address": "0xc2xd69eed00017a7d68a34c19c72226d6aca98f4",
    "privateKey": "33efsa23ra4fa23065f90c51de5a3029bd8143b9fd6819f08a617edc4f8",
    "exported": "2024-08-14T16:04:57.258Z"
  },
  "ts": "2024-08-14T16:04:57.273Z"
}

POST/v1/wallet/custodial/transfer

Transfer from a custodial wallet

This endpoint allows you to transfer funds from a custodial wallet to another wallet. Only ethereum and optimism custodial wallets are supported.

Paremeter

Name
sourceWalletId
Type
string
Required
Required
Description
The id of the custodial wallet to transfer from.
Name
destinationAddress
Type
string
Required
Required
Description
The address to transfer to.
Name
currencyAddress
Type
string
Required
Required
Description
The address of the currency to transfer.
Name
amount
Type
string
Required
Required
Description
The amount to transfer. Must be the raw amount of the currency (e.g., 10 * (10^6) for 10 USDC).

Request

POST

/v1/wallet/custodial/transfer

curl https://api.spherepay.co/v1/wallet/custodial/transfer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{
    \"sourceWalletId\": \"wallet_fd004cb446104d819540c581bbb6e428\",
    \"destinationAddress\": \"0xe2A5947db14a1135c5724BC5BA85868431929A52\",
    \"currencyAddress\": \"0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85\",
    \"amount\": \"1000000\"
  }"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "sourceWalletId": "wallet_fd004cb446104d819540c581bbb6e428",
    "destinationAddress": "0xe2B5947db14a1135c5724BC5BA85868431929A52",
    "currencyAddress": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
    "amount": "1000000",
    "txResponse": {
      "type": 2,
      "chainId": 10,
      "nonce": 0,
      "maxPriorityFeePerGas": { "type": "BigNumber", "hex": "0x48c567" },
      "maxFeePerGas": { "type": "BigNumber", "hex": "0x48c567" },
      "gasPrice": null,
      "gasLimit": { "type": "BigNumber", "hex": "0x013880" },
      "to": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "value": { "type": "BigNumber", "hex": "0x00" },
      "data": "0xa9059cbb000000000000000000000000e2a5947db14a1135c5724bc5ba85868431929a5200000000000000000000000000000000000000000000000000000000000f4240",
      "accessList": [],
      "hash": "0x6b02f3ae70ef403320daed169a37bac0a65d834db98ed573c834790877bd251b",
      "v": 0,
      "r": "0x3f59eb24ec8449455a133307b290587d53263ca6f62b3b8145ada19a00b6cf03",
      "s": "0x5583ad79f50d8e572e0ed82fd5af5ab58a792d4f2391d5c7761c1ec8c1de9db6",
      "from": "0x1d56Ad551Bd147DCfFABe1f76A7e62E71d4c4b90",
      "confirmations": 0
    }
  },
  "ts": "2024-08-15T19:48:30.219Z"
}

POST/v1/wallet/custodial/solana/broadcast/versioned

Broadcast a Solana versioned transaction

This endpoint allows you to export a custodial wallet. Once a custodial wallet is exported, it can no longer be used to sign or send transactions.

Paremeter

Name
versionedTx
Type
string
Required
Required
Description
The versioned transaction to sign. A base64 encoded string representing the serialized versioned transaction.
Name
walletId
Type
string
Required
Required
Description
The id of the wallet to sign with.

Request

POST

/v1/wallet/custodial/solana/broadcast/versioned

curl https://api.spherepay.co/v1/wallet/custodial/solana/broadcast/versioned \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d "{
    \"versionedTx\": \"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQABA4Ykb+nvhGtaP4XX05kP53/wsnbAEsziWbbz7KuCrJLMY38FPCiEylqqDuwtssS6WIPXviZHS13KqdmbQQ1ZqKcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADLCjy4KqUAaPV8mwleHpF8bkKiWg6UmJsTulGaLbpgIAQICAAEMAgAAAADh9QUAAAAAAA==\",
    \"walletId\": \"wallet_27c89779030f4de887d26ec60dc086a0\",
  }"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "versionedTx": "ATxLnj1u50UvaAv7fCZ5TPBntgxKVscpCLUIkh5yAQ0NJuVC4v5MSLCW3ilB2Rm0CItE2EDbtxxD6vTmtImgbwyAAQABA4Ykb+nvhGtaP4XX05kP53/wsnbAEsziWbbz7KuCrJLMY38FPCiEylqqDuwtssS6WIPXviZHS13KqdmbQQ1ZqKcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAANlH4n3smv2zOdTGjulyFCmuSjvQlSUf1HzJi8FkuIqeAQICAAEMAgAAAADh9QUAAAAAAA==",
    "signer": " A2drgynXTRrFavuEYKeQuYtRARikwvSXQWbgcuvoV6UT",
    "txId": "2CvJ6SHCVcHu3HwHgEYaNe9dGXujZD6goypBE7SBS8SQPBskCcC4UK4w7BNr174zR4EBY2iLBpNvdhcGEzdtyKs1"
  },
  "ts": "2024-08-14T16:04:57.273Z"
}