Skip to main content

​
Get User Wallets

curl -X GET https://api.sfluv.org/wallets \
  -H "Authorization: Bearer YOUR_TOKEN"

[
  {
    "id": 1,
    "owner": "did:privy:user123",
    "name": "My Primary Wallet",
    "is_eoa": true,
    "is_redeemer": false,
    "is_minter": false,
    "eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "smart_address": null,
    "smart_index": null,
    "last_unwrap_at": null
  },
  {
    "id": 2,
    "owner": "did:privy:user123",
    "name": "Smart Account",
    "is_eoa": false,
    "is_redeemer": true,
    "is_minter": false,
    "eoa_address": "0x1234567890abcdef1234567890abcdef12345678",
    "smart_address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "smart_index": 0,
    "last_unwrap_at": "2024-03-15T10:30:00Z"
  }
]
Retrieves all wallets associated with the authenticated user. GET /wallets Authentication: Required (Bearer token via Privy)

​
Response Fields

​
id
integer
required
Unique wallet identifier
​
owner
string
required
User’s DID who owns this wallet
​
name
string
required
User-defined wallet name for easy identification
​
is_eoa
boolean
required
Whether this is an Externally Owned Account (true) or Smart Account (false)
​
is_redeemer
boolean
required
Whether this wallet has redeemer role for merchant QR code redemptions
​
is_minter
boolean
required
Whether this wallet has minting privileges
​
eoa_address
string
required
Ethereum address of the EOA (or owner EOA for smart accounts)
​
smart_address
string | null
Smart contract wallet address (null for EOAs)
​
smart_index
integer | null
Index for smart account derivation (null for EOAs)
​
last_unwrap_at
string | null
ISO 8601 timestamp of last token unwrap operation

​
Add Wallet

curl -X POST https://api.sfluv.org/wallets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My MetaMask Wallet",
    "is_eoa": true,
    "eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
  }'

"1"
Adds a new wallet for the authenticated user. POST /wallets Authentication: Required (Bearer token via Privy)

​
Request Body

​
name
string
required
User-defined name for the wallet
​
is_eoa
boolean
required
Whether this is an Externally Owned Account (true) or Smart Account (false)
​
eoa_address
string
required
Ethereum address of the EOA (or owner EOA for smart accounts)
​
smart_address
string
Smart contract wallet address (required if is_eoa is false)
​
smart_index
integer
Index for smart account derivation (required if is_eoa is false)
​
is_redeemer
boolean
Whether this wallet should have redeemer privileges (defaults to false)
​
is_minter
boolean
Whether this wallet should have minting privileges (defaults to false)

​
Response

Returns the newly created wallet’s ID as a string.

​
Special Behavior

When adding a smart account (first wallet with smart_index: 0) for a user who has an approved merchant location, the wallet is automatically granted redeemer role for QR code redemptions.

​
Update Wallet

curl -X PUT https://api.sfluv.org/wallets \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "Updated Wallet Name",
    "is_eoa": true,
    "eoa_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "is_redeemer": true
  }'

{}
Updates an existing wallet’s information. PUT /wallets Authentication: Required (Bearer token via Privy)

​
Request Body

​
id
integer
required
ID of the wallet to update
​
name
string
required
Updated wallet name
​
is_eoa
boolean
required
Whether this is an Externally Owned Account
​
eoa_address
string
required
Ethereum address of the EOA
​
smart_address
string
Smart contract wallet address (for smart accounts)
​
smart_index
integer
Index for smart account derivation (for smart accounts)
​
is_redeemer
boolean
Whether this wallet has redeemer privileges
​
is_minter
boolean
Whether this wallet has minting privileges
​
last_unwrap_at
string
ISO 8601 timestamp of last unwrap operation

​
Response

Returns 201 Created on success with no body.

​
Authorization

Users can only update their own wallets. The owner field is automatically set to the authenticated user’s DID.

​
Wallet Types

​
EOA (Externally Owned Account)

Traditional Ethereum accounts controlled by a private key (e.g., MetaMask, hardware wallets).
  • Set is_eoa: true
  • Only eoa_address is required
  • smart_address and smart_index should be null

​
Smart Account

Contract-based accounts with advanced features like batched transactions and gasless operations.
  • Set is_eoa: false
  • Requires eoa_address (owner), smart_address (contract), and smart_index
  • Used with account abstraction and bundler services

​
Wallet Roles

​
Redeemer Role

Wallets with is_redeemer: true can redeem QR codes for merchant transactions. This role is automatically granted to merchants’ first smart account when they have an approved location.

​
Minter Role

Wallets with is_minter: true have privileges to mint new tokens. This is typically restricted to admin or authorized accounts.

​
Error Responses

​
400 Bad Request
Invalid request format or missing required fields
​
401 Unauthorized
Missing or invalid authentication token
​
403 Forbidden
User does not have permission to access this resource
​
500 Internal Server Error
Server-side error occurred during wallet operation

Build docs developers (and LLMs) love

Get started for freeTalk to us