The wallet object is a convenient way to record public key addresses tied to specific customers across chains, as well as additional features like handling split payments for a given payment method.

Let's take a look at an example wallet object:

The wallet object

{
  "id": "wallet_211dj109jd091d12",
  "address": "7HkGnYsx5P5PLSf2Sx5S1AAdN2LpKY8U1bEArbc7JcsA",
  "isConnectedWallet": true,
  "primary": true,
  "nickname": "My Main Wallet",
  "network": "sol",
  "created": "2021-09-15T12:34:56Z",
  "updated": "2022-05-01T09:30:00Z"
}

isConnectedWallet: boolean True means that this wallet is connected to your Sphere account, currently only available through the dashboard.

Split payments

Sometimes, you may want to create a payment method that shares revenue across different wallets.

To accomplish this we must:

Create a wallet for each wallet that will receive a share of the payment.
Pass in each wallet id that we receive from the API into the wallets field of a payment method.
Define the share of each wallet (in basis points) in the wallets field.

For example, inside a payment link you could pass:

{
  "wallets": [
    {
      "id": "wallet_1",
      "share": 9000
    },
    {
      "id": "wallet_2",
      "shareBps": 1000
    }
  ]
}

Here, wallet_1 will receive 90% (e.g., 9_000 / 10_000) of each payment and wallet_2 will receive 10%.