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:

  1. As the source or destination in transfers.
  2. 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 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"
}

Was this page helpful?