Skip to main content
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

string
required
Your public client key for API authentication
string
required
Bearer token format: Bearer {access_token}
string
required
Must be application/json

Query Parameters

string
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

string
required
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.
string
required
Must be solana for Solana blockchain.Allowed values:
  • solana - Solana mainnet
string
required
SPL token that was approved for delegation.Allowed values:
  • usdc - USD Coin (SPL)
  • usdt - Tether USD (SPL)
string
required
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"
string
required
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.
string
required
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: 2Uhj5WqpLvZmJqKGx3WKvSC5K1m4YCp1eK3jcGY7GgRqNnBQEXhP9XjWCv4M3nZKF7RqWpLvZmJqKGx3WKvSC5K1
string
required
The 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 security
string
required
Single-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

boolean
required
Indicates whether the wallet delegation was completed successfully.

Response Codes

What Happens After Success

When this endpoint returns successfully:
  1. Wallet Registration: The external wallet is registered and linked to the user’s account
  2. Card Payments Enabled: User can now make card purchases using delegated wallet funds
  3. Wallet Visibility: Wallet appears in GET /v1/wallet/external endpoint response
  4. Priority Assignment: Wallet is assigned a default priority for transaction processing
  5. 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, the sigMessage 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
When redelegating, the user must complete a new token account delegation transaction with the updated parameters before calling this endpoint.

Verification After Delegation

After successful delegation, verify the wallet was registered:

Common Error Scenarios

Invalid Transaction Signature

Causes:
  • Transaction hasn’t been confirmed yet
  • Invalid transaction signature format
  • Wrong network (e.g., devnet instead of mainnet)
Solutions:
  • 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

Causes:
  • sigHash doesn’t match the wallet that signed
  • sigMessage was modified after signing
  • Wrong encoding used for signature
Solutions:
  • Ensure the same wallet signs both the delegation and message
  • Don’t modify sigMessage after user signs it
  • Use bs58.encode() for signature encoding

Invalid Address Format

Causes:
  • Address is not base58-encoded
  • Address length is incorrect
  • Contains invalid base58 characters (0, O, I, l)
Solutions:
  • Use publicKey.toBase58() to get correct format
  • Verify address is 32-44 characters
  • Don’t include prefixes or suffixes

Expired Delegation Token

Causes:
  • More than 10 minutes passed since token generation
  • Token was already used in a previous request
Solutions:
  • 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:
Always verify token addresses with official sources before using them in production.

Best Practices

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
Support popular Solana wallets:
  • Phantom (most popular)
  • Solflare
  • Backpack
  • Glow
  • Use @solana/wallet-adapter for easy integration
  • Handle wallet not installed gracefully
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
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)
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

Further Reading

External Resources