Delegation
Complete Solana Wallet Delegation
Finalize delegation of spending authority from Solana wallets (Step 3 of 3)
POST
Overview
This endpoint finalizes the delegation of spending authority from a user’s Solana wallet. After the user has completed wallet connection and token account delegation transaction in your frontend, call this endpoint to register the wallet with the platform.When to Use: Call this endpoint after the user has successfully completed the token account delegation transaction on Solana in your frontend application (Step 2). This is the final step in the delegation workflow for Solana wallets.
Solana-Specific Validation
This endpoint performs strict validation for Solana blockchain:- Address Format: Must be a valid Solana public key (base58-encoded, 32-44 characters)
- Transaction Signature: Must be a valid Solana transaction signature (base58-encoded, 87-88 characters)
- Message Signature: Must be a valid Solana signature (base58-encoded, 87-88 characters)
- Network: Must be
solana
Authentication
Your public client key for API authentication
Bearer token format:
Bearer {access_token}Must be
application/jsonQuery Parameters
Region identifier for environment routing. Use
us for US-specific routing.Example: ?region=usNote: Alternatively, you can use the x-us-env: true header instead of the region query parameter.Request Body
Solana wallet public key that will be delegated. Must be a valid base58-encoded Solana public key (32-44 characters).Pattern:
^[1-9A-HJ-NP-Za-km-z]{32,44}$Example: DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKKThis address must match the one that signed the delegation transaction.Must be
solana for Solana blockchain.Allowed values:solana- Solana mainnet
SPL token that was approved for delegation.Allowed values:
usdc- USD Coin (SPL)usdt- Tether USD (SPL)
Spending limit approved in the delegation. Specified in the currency’s base unit (e.g., 5000 for 5000 USDC). This is the maximum amount the platform can spend from the delegated wallet.Pattern:
^\d+(\.\d+)?$Example: "5000" or "5000.50"Solana transaction signature of the token account delegation. Must be a valid base58-encoded signature (87-88 characters).Pattern:
^[1-9A-HJ-NP-Za-km-z]{87,88}$Example: 5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUWThe API verifies this transaction exists on-chain and is confirmed.Solana signature hash proving wallet ownership. Result of signing
sigMessage with the wallet’s private key. Must be a valid base58-encoded signature (87-88 characters).Pattern: ^[1-9A-HJ-NP-Za-km-z]{87,88}$Example: 2Uhj5WqpLvZmJqKGx3WKvSC5K1m4YCp1eK3jcGY7GgRqNnBQEXhP9XjWCv4M3nZKF7RqWpLvZmJqKGx3WKvSC5K1The message that was signed by the Solana wallet to prove ownership. Can be any string that proves ownership, but should be meaningful.Minimum length: 10 charactersExample:
"Prove wallet ownership for delegation"Recommended format: Include purpose, timestamp, and nonce for securitySingle-use delegation token obtained from
GET /v1/delegation/token (Step 1). Must be a valid UUID.Format: UUID v4Example: 100a99cf-f4d3-4fa1-9be9-2e9828b20ebcNote: Token expires after ~10 minutes or after successful use.Response
Indicates whether the wallet delegation was completed successfully.
Response Codes
| Code | Description |
|---|---|
| 201 | Wallet delegation completed successfully |
| 400 | Bad request - invalid data format or verification failed |
| 401 | Authentication failed - invalid or expired access token |
| 422 | Validation error - invalid request parameters |
| 498 | Invalid client key |
| 499 | Missing client key |
| 500 | Internal server error |
What Happens After Success
When this endpoint returns successfully:- Wallet Registration: The external wallet is registered and linked to the user’s account
- Card Payments Enabled: User can now make card purchases using delegated wallet funds
- Wallet Visibility: Wallet appears in
GET /v1/wallet/externalendpoint response - Priority Assignment: Wallet is assigned a default priority for transaction processing
- Balance Tracking: Platform begins tracking wallet balance and allowance
Solana Token Delegation
On Solana, delegation uses SPL Token’s approve instruction to delegate token account authority:Complete Implementation Example
Here’s a full end-to-end example of the Solana delegation flow:Message Signing
For Solana, thesigMessage should be a clear, descriptive message. Here’s a recommended format:
Redelegation
To update an existing delegation (change allowance, upgrade contracts, etc.), simply call this endpoint again with the same wallet address. The new delegation will replace the previous one. Common redelegation scenarios:- Increase spending limit: User wants to approve a higher amount
- Contract upgrade: Platform deploys new smart contracts
- Token account change: User wants to delegate a different token account
Verification After Delegation
After successful delegation, verify the wallet was registered:Common Error Scenarios
Invalid Transaction Signature
- Transaction hasn’t been confirmed yet
- Invalid transaction signature format
- Wrong network (e.g., devnet instead of mainnet)
- Wait for transaction confirmation (typically 10-30 seconds)
- Verify signature is base58-encoded and 87-88 characters
- Ensure transaction was sent to mainnet
Signature Verification Failed
sigHashdoesn’t match the wallet that signedsigMessagewas modified after signing- Wrong encoding used for signature
- Ensure the same wallet signs both the delegation and message
- Don’t modify
sigMessageafter user signs it - Use
bs58.encode()for signature encoding
Invalid Address Format
- Address is not base58-encoded
- Address length is incorrect
- Contains invalid base58 characters (0, O, I, l)
- Use
publicKey.toBase58()to get correct format - Verify address is 32-44 characters
- Don’t include prefixes or suffixes
Expired Delegation Token
- More than 10 minutes passed since token generation
- Token was already used in a previous request
- Generate a new delegation token from Step 1
- Complete the flow more quickly
- Don’t reuse tokens
SPL Token Addresses
Common SPL token addresses on Solana mainnet:| Token | Mint Address |
|---|---|
| USDC | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
| USDT | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB |
Always verify token addresses with official sources before using them in production.
Best Practices
Transaction Confirmation
Transaction Confirmation
Always wait for transaction confirmation before calling this endpoint:
- Wait for ‘confirmed’ commitment level minimum
- For higher security, wait for ‘finalized’ commitment
- Display transaction status to users
- Implement timeout handling (typically 60 seconds)
- Provide transaction link to Solana Explorer
Wallet Support
Wallet Support
Support popular Solana wallets:
- Phantom (most popular)
- Solflare
- Backpack
- Glow
- Use @solana/wallet-adapter for easy integration
- Handle wallet not installed gracefully
Error Handling
Error Handling
Implement comprehensive error handling:
- Handle user rejection gracefully
- Retry failed transactions with same parameters
- Provide clear error messages to users
- Log errors for debugging (without exposing sensitive data)
- Implement exponential backoff for API retries
Security
Security
Follow security best practices:
- Never store private keys
- Validate all addresses before submission
- Use HTTPS only for all API calls
- Implement rate limiting on your backend
- Verify transaction on blockchain before submitting to API
- Use recent blockhashes (prevent replay attacks)
User Experience
User Experience
Create a smooth user experience:
- Show progress indicators during each step
- Display transaction fees before approval
- Explain delegation in simple terms
- Provide transaction links to Solana Explorer
- Allow users to easily retry on failure
- Show estimated confirmation time
Solana-Specific Considerations
Transaction Fees
Solana transactions require SOL for transaction fees:- Typical fee: 0.000005 SOL (~$0.0001)
- Ensure user has small amount of SOL for fees
- Display estimated fee before transaction
Token Accounts
Users must have a token account for the SPL token:- Check if token account exists before delegation
- Create token account if needed (costs ~0.002 SOL)
- Handle associated token account vs regular token account
Network Congestion
During high network activity:- Transactions may take longer to confirm
- Consider using higher priority fees
- Implement retry logic with exponential backoff
- Display status updates to user
Related Endpoints
- GET /v1/delegation/token - Generate delegation token (Step 1)
- POST /v1/delegation/evm/post-approval - Complete EVM wallet delegation
- GET /v1/wallet/external - List delegated wallets
- Manage External Wallet Priority - Get and update wallet priority order
Further Reading
- Delegation Overview - Understand delegation concepts
- Implementation Guide - Complete integration walkthrough
- Solana Implementation - Detailed Solana-specific implementation
- Priority Management - Managing multiple wallets
- Redelegation - Updating existing delegations