Onchain payments
Onchain payment APIs
Onchain payments enable partners to send and receive supported stablecoins on supported blockchains through Cross River’s regulated banking infrastructure. Cross River facilitates onchain payments using account-bound receiving addresses, external beneficiary management, required compliance checks, and event webhooks for payment status updates.
Get started with Cross River APIs.
GET calls
- Add query parameters to filter the response the API returns to general GET calls.
- Use pagination to control presentation of your results.
Requirements for stablecoin transfers
To use Cross River’s onchain payments API, your account must be configured for both sending and receiving USDC.
Outbound (send)
To originate a transfer, you must have:
- The account number funding the transfer
- The beneficiary address (externalAddressId or inline externalAddress block)
- An amount in either USD or blockchain base units (amount). Provide one or the other, not both.
- The currency (for example, USDC) and blockchain (for example, Ethereum or Solana)
- Proper account and product configuration with outbound crypto permissions
Inbound (receive)
To receive a transfer, you must have:
- A registered account wallet address created through POST /v1/accounts/{accountNumber}/account-addresses
- The currency and blockchain matching the sender’s transfer
- Active inbound payment permissions
- A valid webhook registration to receive onchain payment events
- Required sender PII submitted through POST /v1/payments/{id}/pii, unless sender PII is reused from a previous transfer
For inbound payments, Cross River detects the onchain transfer and issues a Crypto.Payment.OnchainPaymentDetected webhook once the transaction is identified and matched to the account and asset configuration. After required PII is submitted and the payment is completed, Cross River issues a Crypto.Payment.Received webhook.
Monetary amounts
- amount - Either in fiat currency (for example, USD) or blockchain base units for the token (for example, smallest USDC unit)
API calls
This table provides an overview of the onchain APIs described on this site.
Action | API Call | Description |
|---|---|---|
POST /v1/accounts/{accountNumber}/account-addresses | Generate a receiving wallet address for an account | |
POST /v1/accounts/{accountNumber}/external-addresses | Register a payout destination wallet | |
POST /v1/payments | Initiate an outbound transfer | |
GET /v1/accounts/{accountNumber}/account-addresses | Retrieve existing account wallet addresses | |
GET /v1/accounts/{accountNumber}/external-addresses | Retrieve registered beneficiary wallets | |
Send PII | POST /v1/payments/{id}/pii | Adds originator/sender personally identifiable information to an incoming payment |
DELETE /v1/accounts/{accountNumber}/account-addresses/{accountAddressId} | Deletes or disables a blockchain receiving address associated with an account |
Related topics