Delegation
Complete EVM Wallet Delegation
Finalize delegation of spending authority from EVM-compatible wallets (Step 3 of 3)
POST
Overview
This endpoint finalizes the delegation of spending authority from a user’s EVM-compatible external wallet (Linea or Ethereum). After the user has completed wallet connection and blockchain approval 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 blockchain approval transaction on an EVM chain (Linea or Ethereum) in your frontend application (Step 2). This is the final step in the delegation workflow.
EVM-Specific Validation
This endpoint performs strict validation for EVM chains:- Address Format: Must be a valid Ethereum address (0x + 40 hex characters)
- Transaction Hash: Must be a valid EVM transaction hash (0x + 64 hex characters)
- Signature: Must be a valid EVM signature (0x + 130 hex characters)
- SIWE Format: Signature message must follow Sign-In with Ethereum (EIP-4361) standard
- Network: Must be either
lineaorethereum
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 Linea routing.Example: ?region=usNote: When region=us is set or x-us-env: true header is used, Linea transactions are automatically routed to linea-us environment.Request Body
EVM wallet address that will be delegated. Must be a valid Ethereum address starting with
0x followed by 40 hexadecimal characters.Pattern: ^0x[a-fA-F0-9]{40}$Example: 0x3a11a86cf218c448be519728cd3ac5c741fb3424This address must match the one that signed the approval transaction.EVM blockchain network where the approval transaction was executed.Allowed values:
linea- Linea mainnet (Chain ID: 59144)ethereum- Ethereum mainnet (Chain ID: 1)
Stablecoin token that was approved for delegation.Allowed values:
usdc- USD Coinusdt- Tether USD
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"EVM transaction hash of the
approve() call on the token contract. Must start with 0x followed by 64 hexadecimal characters.Pattern: ^0x[a-fA-F0-9]{64}$Example: 0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638The API verifies this transaction exists on-chain and is confirmed.EVM signature hash proving wallet ownership. Result of signing
sigMessage with the wallet’s private key. Must start with 0x followed by 130 hexadecimal characters.Pattern: ^0x[a-fA-F0-9]{130}$Example: 0x2039b9765a4df76e8bae80f3bbc640e8ae6acc81f7a5cc96fe91ccc1844b6f7d4c3e8f1a2b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5bThe SIWE (Sign-In with Ethereum) formatted message that was signed. Must follow the EIP-4361 standard format.Minimum length: 20 charactersRequired SIWE format:
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
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
SIWE Message Format
ThesigMessage must follow the EIP-4361 Sign-In with Ethereum standard:
SIWE Components
- Account Address: Must match the
addressfield - Statement: Can be any text explaining the purpose
- URI: Your application’s domain
- Version: Should be
1 - Chain ID:
59144for Linea,1for Ethereum mainnet - Nonce: Random string for replay protection
- Issued At: ISO8601 timestamp when message was created
- Expiration Time: ISO8601 timestamp when signature expires
Generating SIWE Messages
Complete Implementation Example
Here’s a full end-to-end example of the EVM delegation flow: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
- Network migration: Moving from one blockchain to another
Verification After Delegation
After successful delegation, verify the wallet was registered:Common Error Scenarios
Invalid Transaction Hash
- Transaction hasn’t been confirmed yet
- Wrong network specified
- Invalid transaction hash format
- Wait for transaction confirmation (1-2 blocks)
- Verify the network matches where transaction was executed
- Check transaction hash format (0x + 64 hex characters)
Signature Verification Failed
sigHashdoesn’t match the wallet that signedsigMessagewas modified after signing- Address in SIWE message doesn’t match
addressfield
- Ensure the same wallet signs both the approval and SIWE message
- Don’t modify
sigMessageafter user signs it - Verify address in SIWE message matches the request address field
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
Invalid SIWE Format
- Missing required SIWE fields
- Incorrect field formatting
- Wrong chain ID for network
- Use a SIWE library to generate messages
- Verify all required fields are present
- Ensure chain ID matches network (59144 for Linea, 1 for Ethereum)
Best Practices
Transaction Confirmation
Transaction Confirmation
Always wait for transaction confirmation before calling this endpoint:
- Wait for at least 1 block confirmation
- For higher security, wait for 3-5 confirmations
- Display transaction status to users
- Implement timeout handling (typically 2-3 minutes max)
Error Handling
Error Handling
Implement comprehensive error handling:
- Retry failed transactions with higher gas price
- Handle user rejection gracefully
- 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 and hashes before submission
- Use HTTPS only for all API calls
- Implement rate limiting on your backend
- Verify transaction on blockchain before submitting to API
User Experience
User Experience
Create a smooth user experience:
- Show progress indicators during each step
- Display transaction fees before approval
- Explain what delegation means in simple terms
- Provide transaction links to block explorers
- Allow users to easily retry on failure
Related Endpoints
- GET /v1/delegation/token - Generate delegation token (Step 1)
- POST /v1/delegation/solana/post-approval - Complete Solana 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
- EVM Chains - Detailed EVM-specific implementation
- Priority Management - Managing multiple wallets
- Redelegation - Updating existing delegations