Skip to main content

​
Create Contact

curl -X POST https://api.sfluv.org/contacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "is_favorite": true
  }'

{
  "id": 1,
  "owner": "did:privy:user123",
  "name": "Alice Johnson",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "is_favorite": true
}
Creates a new contact in the authenticated user’s address book. POST /contacts Authentication: Required (Bearer token via Privy)

​
Request Body

​
name
string
required
Display name for the contact
​
address
string
required
Ethereum address of the contact (0x-prefixed hex string)
​
is_favorite
boolean
Whether this contact is marked as a favorite (defaults to false)

​
Response

Returns the created contact object including the auto-generated id and owner fields.
​
id
integer
required
Unique contact identifier
​
owner
string
required
User’s DID who owns this contact
​
name
string
required
Display name for the contact
​
address
string
required
Ethereum address of the contact
​
is_favorite
boolean
required
Whether this contact is marked as a favorite

​
Get Contacts

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

[
  {
    "id": 1,
    "owner": "did:privy:user123",
    "name": "Alice Johnson",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "is_favorite": true
  },
  {
    "id": 2,
    "owner": "did:privy:user123",
    "name": "Bob Smith",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "is_favorite": false
  },
  {
    "id": 3,
    "owner": "did:privy:user123",
    "name": "Charlie's Store",
    "address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "is_favorite": true
  }
]
Retrieves all contacts for the authenticated user. GET /contacts Authentication: Required (Bearer token via Privy)

​
Response

Returns an array of contact objects. The array is empty if the user has no contacts.
​
id
integer
required
Unique contact identifier
​
owner
string
required
User’s DID who owns this contact
​
name
string
required
Display name for the contact
​
address
string
required
Ethereum address of the contact
​
is_favorite
boolean
required
Whether this contact is marked as a favorite

​
Update Contact

curl -X PUT https://api.sfluv.org/contacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "Alice Johnson (Updated)",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "is_favorite": false
  }'

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

​
Request Body

​
id
integer
required
ID of the contact to update
​
name
string
required
Updated display name for the contact
​
address
string
required
Updated Ethereum address of the contact
​
is_favorite
boolean
required
Updated favorite status

​
Response

Returns 201 Created on success with no body.

​
Authorization

Users can only update their own contacts. The system automatically validates that the contact belongs to the authenticated user.

​
Delete Contact

curl -X DELETE 'https://api.sfluv.org/contacts?id=1' \
  -H "Authorization: Bearer YOUR_TOKEN"

{}
Deletes a contact from the authenticated user’s address book. DELETE /contacts Authentication: Required (Bearer token via Privy)

​
Query Parameters

​
id
integer
required
ID of the contact to delete

​
Response

Returns 200 OK on success with no body.

​
Authorization

Users can only delete their own contacts. The system automatically validates that the contact belongs to the authenticated user before deletion.

​
Use Cases

​
Address Book for Transactions

Contacts serve as a user-friendly address book for cryptocurrency transactions within SFLUV:
  • Store frequently used wallet addresses with memorable names
  • Mark favorite contacts for quick access
  • Avoid copying/pasting long Ethereum addresses

​
Merchant Contacts

Users can save their favorite merchant locations’ wallet addresses for easy payments: 
{
  "name": "Joe's Coffee Shop",
  "address": "0x...",
  "is_favorite": true
}

​
Personal Network

Maintain a list of friends, family, or colleagues for peer-to-peer transfers: 
[
  {
    "name": "Mom",
    "address": "0x...",
    "is_favorite": true
  },
  {
    "name": "John - Coworker",
    "address": "0x...",
    "is_favorite": false
  }
]

​
Best Practices

​
Address Validation

Always validate Ethereum addresses on the client side before submitting:
  • Must start with 0x
  • Must be 42 characters long (0x + 40 hex characters)
  • Must contain only valid hexadecimal characters (0-9, a-f, A-F)

​
Favorite Management

Use the is_favorite flag to:
  • Highlight important contacts in the UI
  • Sort favorites to the top of contact lists
  • Provide quick access buttons for frequent recipients

​
Contact Names

Recommend users include context in contact names:
  • ✅ “Alice - Landlord”
  • ✅ “Bob’s Hardware Store”
  • ✅ “Mom’s Wallet”
  • ❌ “Alice” (too generic if user knows multiple Alices)

​
Error Responses

​
400 Bad Request
Invalid request format, missing required fields, or invalid contact ID
​
401 Unauthorized
Missing or invalid authentication token
​
500 Internal Server Error
Server-side error occurred during contact operation

​
Security Notes

  • All contact operations are scoped to the authenticated user
  • Users cannot access or modify other users’ contacts
  • The owner field is automatically set from the authentication token and cannot be overridden
  • Contact data is stored securely in the PostgreSQL database

Build docs developers (and LLMs) love

Get started for freeTalk to us