Wallets and address management
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
POST /v1/accounts/2917000057/account-addresses
{
"blockchain": "solana",
"currency": "usdc"
}Example response
{
"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
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
{
"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"
}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 |