Bind wallet
Connect existing third-party wallets to customer accounts
Bind Wallet
Purpose: Connect existing wallets from third-party providers (MetaMask, Trust Wallet, Coinbase Wallet) to customer accounts.
Binded wallets are non-custodial - Your customers retain full control of their private keys. Swipelux tracks the wallet address and enables transfers, but cannot initiate payouts/withdrawals since we don't control the private keys.
When to Use Bind
Use wallet binding for:
- Users with existing MetaMask, Trust Wallet, or similar wallets
- Non-custodial wallet solutions
- Users who prefer to manage their own private keys
- Web3-native users who want to keep their existing wallets
For new users without wallets, see Create Wallet.
Important: Binded wallets do NOT support payout/withdrawal operations via the API. Users can only receive funds and initiate transfers. For withdrawals, users must use their wallet provider directly.
Request Parameters
| Field | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Blockchain address (must be valid EVM address) |
chain | string | Yes | Blockchain network (base, polygon) |
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Wallet identifier (use for transfers) |
address | string | Blockchain address |
chain | string | Blockchain network |
currency | string | Supported currency (USDC) |
bound | boolean | Always true for binded wallets |
createdAt | string | ISO 8601 timestamp |
Key Differences from Created Wallets
| Feature | Created Wallet | Binded Wallet |
|---|---|---|
| Private Keys | Managed by Swipelux | Managed by user |
| Control | Custodial | Non-custodial |
| Receive Funds | Yes | Yes |
| Transfers (API) | Yes | Yes |
| Payouts (API) | Yes | No |
| Withdrawals | Via Swipelux API | Via user's wallet app |
| Use Case | New users | Web3-native users |
Supported Operations
What binded wallets CAN do:
- Receive funds via pay-ins
- Track balance via API
- Initiate transfers to other wallets
- Monitor transaction history
What binded wallets CANNOT do:
- API-initiated withdrawals/payouts
- Automated settlements
- Programmatic fund movements without user signature
Address Validation
The API validates that:
- Address is a valid EVM address format
- Address checksum is correct (case-sensitive validation)
- Chain is supported (
ethereum,base,polygon) - Address is not already binded to another customer
User Flow Example
- User connects MetaMask wallet to your application
- Your app captures the wallet address
- Call
POST /v1/customers/{id}/wallets/bindwith the address - User can now receive funds at this address
- Track incoming funds via balance API
- For withdrawals, user signs transactions in MetaMask directly
Next Steps
After binding wallets:
- Set up Pay-ins - Get wallet address for receiving funds
- Monitor Balances - Track wallet balances
- Create Transfers - Move funds between wallets
Note: Payouts are not supported for binded wallets.
Error Responses
| Status | Error | Solution |
|---|---|---|
400 | Invalid address | Provide valid EVM address with correct checksum |
400 | Invalid chain | Use supported chains: ethereum, base, polygon |
404 | Customer not found | Create the customer first using POST /v1/customers |
409 | Address already binded | This address is already associated with a customer |