---
title: Wallets and address management
slug: concepts/onchain-payments/wallets-and-address-management
description: Discover Cross River's crypto payments API, enabling secure management of account and external beneficiary wallets for seamless USDC transactions on Ethereum and Solana.
docTags: 
createdAt: 2025-11-23T08:58:37.472Z
---

## Wallets in Cross River

The Cross River stablecoin payments API supports two types of blockchain address records: **wallets linked to accounts** and **external beneficiary wallets**. These records are managed within Cross River infrastructure and associated with an account to support traceability and operational consistency.

## Wallets linked to accounts

Wallets linked to accounts are bank managed onchain addresses associated with a specific Cross River account. They are used exclusively to receive **inbound stablecoin payments** from external blockchain addresses.

### Wallet linked to accounts attributes

| Field                     | Description                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Purpose**               | Receive inbound stablecoin payments from external blockchain addresses                               |
| **Association**           | Each wallet is associated with a unique Cross River account                                          |
| **Creation**              | Generate using the `POST /v1/accounts/{accountNumber}/account-addresses` endpoint                    |
| **Retrieval**             | Retrieve using `GET /v1/accounts/{accountNumber}/account-addresses`                                  |
| **Blockchains supported** | Ethereum and Solana                                                                                  |
| **Security**              | Wallet addresses are managed within Cross River infrastructure. Partners do not manage private keys. |

**Example request**

```curl
POST /v1/accounts/2917000057/account-addresses
{
 "blockchain": "solana",
 "currency": "usdc"
}
```

**Example response**

```json
{
  "id": "108489fd-9f2f-4b1d-9a4e-b39d01164422",
  "accountNumber": "2917000057",
  "blockchain": "solana",
  "address": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
  "title": "solana",
  "lastModifiedAt": "2025-11-22T16:53:08.1639985Z"
}
```

## External beneficiary wallets

External beneficiary wallets represent approved **outbound payment destinations** that may be registered and reused when initiating stablecoin payments to external blockchain addresses, which may be Cross River’s customer or the customer’s customer (i.e. the end user)

### External beneficiary wallet attributes

| Field                     | Description                                                                      |
| ------------------------- | -------------------------------------------------------------------------------- |
| **Purpose**               | Send outbound stablecoin payments to an external blockchain address              |
| **Association**           | Each external beneficiary wallet is associated with a Cross River account        |
| **Creation**              | Create using the `POST /v1/accounts/{accountNumber}/external-addresses` endpoint |
| **Retrieval**             | Retrieve using `GET /v1/accounts/{accountNumber}/external-addresses`             |
| **Beneficiary details**   | Includes recipient identifying information for compliance review                 |
| **Blockchains supported** | Ethereum and Solana                                                              |

**Example request**

```curl
POST /v1/accounts/2917000057/external-addresses
{
  "title": "Supplier Wallet",
  "blockchain": "ethereum",
  "address": "0x0e6f76783822826ED173fEE6265bDbbdfEd4a0F5",
  "currency": "usdc",
  "beneficiary": {
    "name": "ABC Supplier LLC",
    "addressLine1": "500 Commerce Ave",
    "city": "Jersey City",
    "stateProvince": "NJ",
    "countryCode": "US",
    "postalCode": "07302"
  }
}
```

**Example response**

```json
{
  "id": "6d5a90a0-4967-44ba-8380-b39d011abba0",
  "accountNumber": "2917000057",
  "title": "Supplier Wallet",
  "blockchain": "ethereum",
  "address": "0x0e6f76783822826ED173fEE6265bDbbdfEd4a0F5",
  "beneficiary": {
    "name": "ABC Supplier LLC",
    "addressLine1": "500 Commerce Ave",
    "city": "Jersey City",
    "stateProvince": "NJ",
    "countryCode": "US",
    "postalCode": "07302"
  },
  "lastModifiedAt": "2025-11-22T17:09:23.9971536Z"
}
```

[Learn how to send onchain payments](docId:97ecBPkLpcwxVCxKeo_la)

## Operational overview

| Wallet type                     | Direction | Managed by                 | Description                                       |
| ------------------------------- | --------- | -------------------------- | ------------------------------------------------- |
| **Wallets linked to accounts**  | Inbound   | Cross River                | Receives USDC from external blockchain addresses  |
| **External beneficiary wallet** | Outbound  | Registered through the API | Used to send USDC to approved external recipients |

## Best practices

Follow these recommendations when managing wallet records through the API:

| Practice                                    | Description                                                                                    |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Use descriptive titles**                  | Assign clear names such as “USDC Solana Address” or “Vendor Payout Address” for identification |
| **Maintain consistent blockchain mappings** | Create wallet records on the same network used for the intended payment flow                   |
| **Validate external addresses before use**  | Verify destination addresses through internal procedures prior to initiating payments          |
| **Limit wallet creation**                   | Reuse existing wallet records where possible to maintain a clear audit trail                   |
| **Monitor modification timestamps**         | Use `lastModifiedAt` to track creation and updates for reporting and operational review        |