Update Wallet

Update wallet properties including username and profile picture.

PATCH/v1/wallets/{wallet_id}

Overview

Update wallet properties including username and picture_url. Users can only update their own wallet.

Authentication

Required: Yes (wallet signature)
Payment: No

Parameters

Path Parameters

Parameter	Type	Required	Description
`wallet_id`	string (UUID)	Yes	Wallet identifier

Request Headers

Header	Type	Required	Description
`x-wallet-address`	string	Yes	Ethereum wallet address (0x prefixed)
`x-signature`	string	Yes	Cryptographic signature (hex format)
`x-message`	string	Yes	The signed message (base64 encoded if contains newlines)
`x-timestamp`	string	Yes	Unix timestamp in seconds
`x-chain-id`	string	No	Chain ID for network detection. Supported: 8453 (base), 84532 (base-sepolia), 1 (ethereum), 11155111 (ethereum-sepolia), 137 (polygon), 80002 (polygon-amoy)

Request Body

Parameter	Type	Required	Description
`username`	string	No	Username for the wallet (alphanumeric, 3-50 characters)
`picture_url`	string (URI)	No	Profile picture URL

Request Body Example

{
  "username": "cryptouser123",
  "picture_url": "https://example.com/profile-pic.jpg"
}

Response

Status: 200 OK

{
  "id": "string",
  "address": "string",
  "network": "string",
  "username": "string",
  "picture_url": "string",
  "total_feeds": number,
  "total_entries": number,
  "total_revenue": "string",
  "created_at": number,
  "updated_at": number
}

Response Fields

Field	Type	Description
`id`	string	Unique wallet identifier
`address`	string	Ethereum wallet address
`network`	string	Blockchain network
`username`	string	Updated username
`picture_url`	string	Updated profile picture URL
`total_feeds`	number	Number of feeds created by this wallet
`total_entries`	number	Number of entries created by this wallet
`total_revenue`	string	Total revenue earned (in wei)
`created_at`	number	Wallet creation timestamp
`updated_at`	number	Last update timestamp

Usage Examples

cURL

curl -X PATCH https://api.grapevine.fyi/v1/wallets/{wallet_id} \
  -H "Content-Type: application/json" \
  -H "x-wallet-address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
  -H "x-signature: 0x..." \
  -H "x-message: Sign this message..." \
  -H "x-timestamp: 1234567890" \
  -H "x-chain-id: 8453" \
  -d '{
    "username": "cryptouser123",
    "picture_url": "https://example.com/profile-pic.jpg"
  }'

SDK Usage

// The SDK doesn't expose wallet update directly
// Use the client utilities and direct API calls:
import { GrapevineClient } from '@pinata/grapevine-sdk';
 
const grapevine = new GrapevineClient({
  privateKey: process.env.PRIVATE_KEY
});
 
// Get your wallet ID first
const walletAddress = grapevine.getWalletAddress();
console.log('Your wallet address:', walletAddress);
 
// Then use direct API call to update
const response = await grapevine.client.patch(`/wallets/${walletId}`, {
  username: 'mynewusername',
  picture_url: 'https://example.com/new-pic.jpg'
});

Error Responses

400 Bad Request

{
  "error": "Invalid username format",
  "code": "INVALID_USERNAME",
  "details": "Username must be 3-50 alphanumeric characters"
}

401 Unauthorized

{
  "error": "Invalid signature",
  "code": "INVALID_SIGNATURE"
}

403 Forbidden

{
  "error": "Cannot update another user's wallet",
  "code": "UNAUTHORIZED_WALLET_UPDATE"
}

404 Not Found

{
  "error": "Wallet not found",
  "code": "WALLET_NOT_FOUND"
}

409 Conflict

{
  "error": "Username already taken",
  "code": "USERNAME_CONFLICT"
}

Validation Rules

Username

Length: 3-50 characters
Format: Alphanumeric characters only (a-z, A-Z, 0-9)
Uniqueness: Must be unique across all wallets

Picture URL

Format: Valid HTTP/HTTPS URL
File types: Recommended image formats (PNG, JPG, GIF, SVG)
Size: Recommended max 1MB for optimal loading

Use Cases

1. Set Initial Profile

{
  "username": "newuser123",
  "picture_url": "https://cdn.example.com/avatars/default.png"
}

2. Update Username Only

{
  "username": "coolername456"
}

3. Update Profile Picture Only

{
  "picture_url": "https://cdn.example.com/avatars/new-avatar.jpg"
}

Notes

Ownership: Only wallet owners can update their own wallet
Partial Updates: Provide only the fields you want to change
Username Uniqueness: Usernames must be unique across the platform
Profile Pictures: External URLs recommended for better performance
Authentication: Standard wallet signature authentication required

Related Endpoints

GET /v1/wallets/{wallet_id} - Get wallet details
GET /v1/wallets/{wallet_id}/stats - Get wallet statistics
GET /v1/wallets/address/{address} - Get wallet by address

External Playground

Try this endpoint interactively in Swagger UI:
https://api.grapevine.fyi/v1/docs