The External Wallet object

External wallets are Solana wallet addresses associated with a connected account for receiving USDC payouts. They are the crypto equivalent of bank accounts in traditional payment systems.

Stripe API equivalent

Create an external wallet

POST /v1/accounts/:id/external_accounts

Update an external wallet

POST /v1/accounts/:id/external_accounts/:id

Retrieve an external wallet

GET /v1/accounts/:id/external_accounts/:id

List all external wallets

GET /v1/accounts/:id/external_accounts

Delete an external wallet

DELETE /v1/accounts/:id/external_accounts/:id

Attributes

id string

Unique identifier for the object. Zoneless external wallet IDs are prefixed with wa_z_.

object string

String representing the object's type. Objects of the same type share the same value. Always wallet.

Difference from Stripe: Stripe returns bank_account. Zoneless returns wallet for Solana wallets.

accountnullable string

The Zoneless account this wallet belongs to.

account_holder_namenullable string

The name of the person or business that owns the wallet.

account_holder_typenullable enum

The type of entity that holds the wallet.

Possible enum values

individualA person who owns the wallet.

companyA business entity that owns the wallet.

available_payout_methodsnullable array of enums

A set of available payout methods for this wallet. Only values from this set should be passed as the method when creating a payout.

Difference from Stripe: Solana transactions are inherently fast, so instant is always available.

Possible enum values

instantImmediate transfer to the wallet. Default for Solana.

standardStandard transfer timing.

country string

Two-letter ISO code representing the country of the wallet holder.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

currency string

Three-letter currency code representing the currency for payouts. For Zoneless, this is typically usdc.

Difference from Stripe: Stripe uses ISO currency codes like usd. Zoneless uses usdc for USDC stablecoin.

customernullable string

The ID of the customer that the wallet is associated with, if applicable.

default_for_currencynullable boolean

Whether this wallet is the default external account for its currency. When creating a payout without specifying a destination, the default wallet is used.

fingerprintnullable string

Uniquely identifies this particular wallet. You can use this attribute to check whether two wallets are the same.

future_requirementsnullable object

Information about upcoming new requirements for the wallet.

last4 string

The last four characters of the wallet address.

Difference from Stripe: Stripe shows last 4 digits of bank account. Zoneless shows last 4 characters of the Solana wallet address.

metadatanullable object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

network string

The blockchain network this wallet is on. Currently always solana.

Zoneless extension: This field is not present in Stripe's API. It identifies the blockchain network.

requirementsnullable object

Information about the requirements for the wallet, including what information needs to be collected.

status enum

The status of the wallet.

Difference from Stripe: Stripe has additional statuses like tokenized_account_number_deactivated which don't apply to crypto wallets.

Possible enum values

newThe wallet has been added but no payouts have been sent yet.

validatedThe wallet address has been validated as a valid Solana address.

verifiedThe wallet has been fully verified.

verification_failedVerification failed. Check requirements.errors for details.

erroredA payout to this wallet failed. Check recent payouts for details.

archivedThe wallet has been archived and is no longer eligible for payouts.

wallet_address string

The full Solana wallet address where USDC payouts are sent.

Zoneless extension: This replaces Stripe's account_number and routing_number. Solana addresses are typically 32-44 characters.

More attributes

THE EXTERNAL WALLET OBJECT

{
  "id": "wa_z_1Nv0FGQ9RKHgCVdK",
  "object": "wallet",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "account_holder_name": "Tom Jones",
  "account_holder_type": "individual",
  "available_payout_methods": [
    "standard",
    "instant"
  ],
  "country": "US",
  "created": 1704067200,
  "currency": "usdc",
  "customer": null,
  "default_for_currency": true,
  "fingerprint": null,
  "future_requirements": null,
  "last4": "9dKq",
  "metadata": {},
  "network": "solana",
  "platform_account": "acct_z_Platform123abc",
  "requirements": null,
  "status": "new",
  "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsD"
}

Create an external wallet

Creates a new external wallet for a connected account. The wallet address is screened against sanctions lists before being added.

ENDPOINTS

POST /v1/accounts/:id/external_accounts

Parameters

wallet_address string Required

The Solana wallet address where USDC payouts will be sent. This must be a valid Solana address (typically 32-44 characters).

Difference from Stripe: Replaces Stripe's external_account object with bank account details. Zoneless only requires the wallet address.

account_holder_name string

The name of the person or business that owns the wallet.

account_holder_type enum

The type of entity that holds the wallet.

Possible enum values

individualA person who owns the wallet.

companyA business entity that owns the wallet.

currency string

Three-letter currency code. Defaults to usdc.

default_for_currency boolean

When set to true, or if this is the first external account added in this currency, this wallet becomes the default for that currency.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

network string

The blockchain network. Defaults to solana.

Zoneless extension: This field is not present in Stripe's API.

Returns

Returns the External Wallet object if the wallet was created successfully. Returns an error if the wallet address is invalid, already in use, or on a sanctions list.

POST/v1/accounts/:id/external_accounts

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const externalWallet = await zoneless.accounts.createExternalAccount(
  'acct_z_1Nv0FGQ9RKHgCVdK',
  {
    wallet_address: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsD',
  }
);

RESPONSE

{
  "id": "wa_z_1Nv0FGQ9RKHgCVdK",
  "object": "wallet",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "account_holder_name": null,
  "account_holder_type": null,
  "available_payout_methods": [
    "standard",
    "instant"
  ],
  "country": null,
  "created": 1704067200,
  "currency": "usdc",
  "customer": null,
  "default_for_currency": true,
  "fingerprint": null,
  "future_requirements": null,
  "last4": "9dKq",
  "metadata": {},
  "network": "solana",
  "platform_account": "acct_z_Platform123abc",
  "requirements": null,
  "status": "new",
  "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsD"
}

Update an external wallet

Updates the metadata, account holder name, account holder type, and default status of an external wallet. The wallet address cannot be changed—delete and create a new wallet instead.

ENDPOINTS

POST /v1/accounts/:id/external_accounts/:id

Parameters

account_holder_name string

The name of the person or business that owns the wallet.

account_holder_type enum

The type of entity that holds the wallet.

Possible enum values

individualA person who owns the wallet.

companyA business entity that owns the wallet.

default_for_currency boolean

When set to true, this becomes the default external wallet for its currency.

metadata object

Set of key-value pairs that you can attach to an object. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

Returns the updated External Wallet object if the call succeeds.

POST/v1/accounts/:id/external_accounts/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const externalWallet = await zoneless.accounts.updateExternalAccount(
  'acct_z_1Nv0FGQ9RKHgCVdK',
  'wa_z_1Nv0FGQ9RKHgCVdK',
  {
    account_holder_name: 'Tom Jones',
    metadata: {
      order_id: '6735',
    },
  }
);

RESPONSE

{
  "id": "wa_z_1Nv0FGQ9RKHgCVdK",
  "object": "wallet",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "account_holder_name": "Tom Jones",
  "account_holder_type": "individual",
  "available_payout_methods": [
    "standard",
    "instant"
  ],
  "country": null,
  "created": 1704067200,
  "currency": "usdc",
  "customer": null,
  "default_for_currency": true,
  "fingerprint": null,
  "future_requirements": null,
  "last4": "9dKq",
  "metadata": {
    "order_id": "6735"
  },
  "network": "solana",
  "platform_account": "acct_z_Platform123abc",
  "requirements": null,
  "status": "new",
  "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsD"
}

Retrieve an external wallet

Retrieves the details of an existing external wallet. Supply the unique wallet ID and the account ID it belongs to.

ENDPOINTS

GET /v1/accounts/:id/external_accounts/:id

Parameters

No parameters.

Returns

Returns the External Wallet object if a valid identifier was provided. Raises an error if the wallet doesn't exist or doesn't belong to the specified account.

GET/v1/accounts/:id/external_accounts/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const externalWallet = await zoneless.accounts.retrieveExternalAccount(
  'acct_z_1Nv0FGQ9RKHgCVdK',
  'wa_z_1Nv0FGQ9RKHgCVdK'
);

RESPONSE

{
  "id": "wa_z_1Nv0FGQ9RKHgCVdK",
  "object": "wallet",
  "account": "acct_z_1Nv0FGQ9RKHgCVdK",
  "account_holder_name": "Tom Jones",
  "account_holder_type": "individual",
  "available_payout_methods": [
    "standard",
    "instant"
  ],
  "country": "US",
  "created": 1704067200,
  "currency": "usdc",
  "customer": null,
  "default_for_currency": true,
  "fingerprint": null,
  "future_requirements": null,
  "last4": "9dKq",
  "metadata": {},
  "network": "solana",
  "platform_account": "acct_z_Platform123abc",
  "requirements": null,
  "status": "new",
  "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsD"
}

List all external wallets

Returns a list of external wallets for a given connected account. The wallets are returned in sorted order, with the most recently created wallets appearing first.

ENDPOINTS

GET /v1/accounts/:id/external_accounts

Parameters

ending_before string

A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with wa_z_bar, your subsequent call can include ending_before=wa_z_bar in order to fetch the previous page of the list.

limit integer

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

starting_after string

A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with wa_z_foo, your subsequent call can include starting_after=wa_z_foo in order to fetch the next page of the list.

Returns

A dictionary with a data property that contains an array of up to limit external wallets. If no wallets are available, the resulting array is empty.

GET/v1/accounts/:id/external_accounts

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const externalWallets = await zoneless.accounts.listExternalAccounts(
  'acct_z_1Nv0FGQ9RKHgCVdK',
  {
    limit: 3,
  }
);

RESPONSE

{
  "object": "list",
  "url": "/v1/accounts/acct_z_1Nv0FGQ9RKHgCVdK/external_accounts",
  "has_more": false,
  "data": [
    {
      "id": "wa_z_1Nv0FGQ9RKHgCVdK",
      "object": "wallet",
      "account": "acct_z_1Nv0FGQ9RKHgCVdK",
      "account_holder_name": "Tom Jones",
      "account_holder_type": "individual",
      "available_payout_methods": [
        "standard",
        "instant"
      ],
      "country": "US",
      "created": 1704067200,
      "currency": "usdc",
      "customer": null,
      "default_for_currency": true,
      "fingerprint": null,
      "future_requirements": null,
      "last4": "9dKq",
      "metadata": {},
      "network": "solana",
      "platform_account": "acct_z_Platform123abc",
      "requirements": null,
      "status": "new",
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsD"
    }
  ]
}

Delete an external wallet

Deletes an external wallet from a connected account. Once deleted, the wallet can no longer receive payouts.

ENDPOINTS

DELETE /v1/accounts/:id/external_accounts/:id

Parameters

No parameters.

Returns

Returns an object with a deleted parameter if the deletion succeeds. Returns an error if the wallet doesn't exist or cannot be deleted.

DELETE/v1/accounts/:id/external_accounts/:id

import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const deleted = await zoneless.accounts.deleteExternalAccount(
  'acct_z_1Nv0FGQ9RKHgCVdK',
  'wa_z_1Nv0FGQ9RKHgCVdK'
);

RESPONSE

{
  "id": "wa_z_1Nv0FGQ9RKHgCVdK",
  "object": "wallet",
  "deleted": true
}