API Reference

wallets

7 endpoints

/api/v1/wallets

GET/api/v1/wallets

List Wallets

List all wallets owned by the current user.

Set details=true to include balance and organization/membership context.

Query parameters

details	boolean	Include balance and context information default: false
default_backend	string	default: "primary"
page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

PaginatedResponse_UserWalletResponse_ | PaginatedResponse_UserWalletWithContextResponse_

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X GET "https://api.davi.social/api/v1/wallets" \
  -H "Authorization: Bearer <token>"

GET/api/v1/wallets/{wallet_address}

Get Wallet

Get a wallet by its address.

Path parameters

wallet_address*

string

Responses

200Successful Response

Field	Type	Description
address*	string	Wallet address
uuid*	string	Wallet UUID
user_uuid	string \| null	Owner user UUID (None for org treasury wallets)
public_key_pem*	string	Public key in PEM format

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X GET "https://api.davi.social/api/v1/wallets/{wallet_address}" \
  -H "Authorization: Bearer <token>"

GET/api/v1/wallets/{wallet_address}/balance

Get Wallet Balance

Get a wallet's current point balance.

Path parameters

wallet_address*

string

Responses

200Successful Response

Field	Type	Description
balance*	number	Current wallet balance

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X GET "https://api.davi.social/api/v1/wallets/{wallet_address}/balance" \
  -H "Authorization: Bearer <token>"

GET/api/v1/wallets/{wallet_address}/details

Get Wallet Details

Get wallet with balance and organization/membership context.

Returns the wallet with its current balance, organization context, and membership information if applicable.

Path parameters

wallet_address*

string

Responses

200Successful Response

Field

Type

Description

wallet_uuid*

string

Wallet UUID

wallet_address*

string

Wallet address

balance*

number

Current wallet balance

is_primary*

boolean

Whether this is the user's primary wallet

organization

WalletOrganizationInfo | null

Organization this wallet belongs to, if any

object · WalletOrganizationInfo

Field	Type	Description
uuid*	string	Organization UUID
name*	string	Organization name
slug*	string	Organization slug

membership

WalletMembershipInfo | null

Membership associated with this wallet, if any

object · WalletMembershipInfo

Field	Type	Description
uuid*	string	UserMembership UUID
tier_name*	string	Membership tier name
joined_at*	string (date-time)	When user joined this membership

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X GET "https://api.davi.social/api/v1/wallets/{wallet_address}/details" \
  -H "Authorization: Bearer <token>"

GET/api/v1/wallets/{wallet_address}/transactions

Get Transaction History

List a wallet's transactions, most recent first.

Path parameters

wallet_address*

string

Query parameters

page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

Transaction[]

List of items on the current page

array items · Transaction

Field	Type	Description
id*	string	Transaction ID (CUID2)
from_address*	string	Sender wallet address
to_address*	string	Receiver wallet address
amount*	number	Transaction amount
transaction_type*	string	Type of transaction
status*	string	Status of the transaction
transaction_hash*	string	Hash of the transaction
previous_hash*	string	Hash of the previous transaction
signature*	string	Digital signature of the transaction
public_key*	string	Public key in PEM format
encrypted_data*	string	Encrypted transaction data
data_hash*	string	Hash of the transaction data
description*	string	Description of the transaction
reference_id*	string	Reference ID for the transaction
original_transaction_id*	string	Original transaction ID for reversals/refunds (CUID2)
failure_reason*	string	Reason for failure, if any
reversal_reason*	string	Reason for reversal, if any
failed_at*	string (date-time) \| null	Timestamp when the transaction failed
created_at*	string (date-time)	Timestamp when the transaction was created
confirmed_at*	string (date-time) \| null	Timestamp when the transaction was confirmed
tags	string[]	Tags attached to the transaction at creation time

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X GET "https://api.davi.social/api/v1/wallets/{wallet_address}/transactions" \
  -H "Authorization: Bearer <token>"

GET/api/v1/wallets/{wallet_address}/transactions/recent

Get Recent Transactions

Get recent transactions with enriched sender information.

Returns transactions with human-readable sender names (when available) and transaction type labels. For transactions created before sender metadata was stored, falls back to wallet address.

Path parameters

wallet_address*

string

Query parameters

page	integer	default: 1 · ≥ 1
page_size	integer	default: 20 · ≥ 1 · ≤ 100
sort_by	string \| null
sort_order	string	default: "asc"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

RecentTransactionItem[]

List of items on the current page

array items · RecentTransactionItem

Field	Type	Description
transaction_id*	string	Transaction ID (CUID2)
transaction_type*	enum	Type: transfer, reward, refund, etc.
direction*	enum	'incoming' if wallet received, 'outgoing' if wallet sent
sender_name*	string	Sender name from metadata, or wallet address as fallback
sender_address*	string	Sender wallet address
amount*	number	Transaction amount in points
created_at*	string (date-time)	Transaction timestamp
has_reward_content	boolean \| null	For reward transactions: True if has content (voucher, etc.), False if points-only. None for non-reward types.

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X GET "https://api.davi.social/api/v1/wallets/{wallet_address}/transactions/recent" \
  -H "Authorization: Bearer <token>"

POST/api/v1/wallets/primary

Create Primary Wallet

Ensure the current user has a primary wallet and a primary virtual card.

Idempotent. Returns 201 Created when the wallet is created this request, 200 OK when returning an already-existing primary wallet.

Query parameters

default_backend

string

default: "primary"

Responses

200Primary wallet already existed; returned unchanged.

Field	Type	Description
wallet_uuid*	string	Created wallet UUID
wallet_address*	string	Created wallet address
virtual_card_uuid	string \| null	Created virtual card UUID (primary identity anchor)

201Successful Response

Field	Type	Description
wallet_uuid*	string	Created wallet UUID
wallet_address*	string	Created wallet address
virtual_card_uuid	string \| null	Created virtual card UUID (primary identity anchor)

400Invalid request

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code
details	object \| null	What the refusal is about, where it is something you can act on — the amount and currency owed on a `402`, the entitlement a tier did not grant on a `403`. Values are typed as the error carries them, so read a figure from here rather than from `errors`, whose values are always the copy a form shows against a field.

Example request

curl -X POST "https://api.davi.social/api/v1/wallets/primary" \
  -H "Authorization: Bearer <token>"