Donations
Donations allow supporters to send one-time USDC payments to creators as a way to show appreciation. Unlike memberships, donations are not recurring and can include a personal message.
The Donation Model
Properties
- Name
id- Type
- string
- Description
Unique identifier for the donation transaction.
- Name
donor- Type
- string
- Description
Sui address of the donor.
- Name
creator- Type
- string
- Description
Sui address of the receiving creator.
- Name
amount- Type
- string
- Description
Donation amount in USDC (max 6 decimal places).
- Name
message- Type
- string
- Description
Optional message from the donor (max 30 words).
- Name
created_at- Type
- timestamp
- Description
Timestamp of the donation.
- Name
tx_hash- Type
- string
- Description
Sui blockchain transaction hash.
Send Donation
Send a one-time donation to a creator.
Required attributes
- Name
creator- Type
- string
- Description
The Sui address of the creator to donate to.
- Name
amount- Type
- string
- Description
Donation amount in USDC (e.g., "5.00").
Optional attributes
- Name
message- Type
- string
- Description
A message to the creator (max 30 words).
Limits
- Minimum donation: 0.01 USDC
- Maximum donation: 10,000 USDC
- Transaction fee: ~0.001 USDC
Request
curl https://api.zing.protocol/v1/donate \
-H "Authorization: Bearer {jwt_token}" \
-d creator="0x123...creator" \
-d amount="5.00" \
-d message="Love your work!"
List Donations Received
Get all donations received by a creator.
Path parameters
- Name
address- Type
- string
- Description
The creator's Sui address.
Query parameters
- Name
limit- Type
- integer
- Description
Number of results to return (default: 10).
- Name
cursor- Type
- string
- Description
Pagination cursor for next page.
Request
curl https://api.zing.protocol/v1/creators/0x123.../donations \
-H "Authorization: Bearer {jwt_token}"
List My Donations Made
Get all donations made by the authenticated user.
Query parameters
- Name
limit- Type
- integer
- Description
Number of results to return (default: 10).
- Name
cursor- Type
- string
- Description
Pagination cursor for next page.
Request
curl https://api.zing.protocol/v1/donations \
-H "Authorization: Bearer {jwt_token}"
Donation Dialog Flow
User clicks "Donate" button on creator profile
↓
Donation dialog opens showing:
- Creator name and avatar
- User's USDC balance
- Amount input field
- Optional message textarea
↓
User enters amount and optional message
↓
Real-time validation:
- Amount must be > 0.01 USDC
- Amount must be <= balance
- Message max 30 words
↓
User clicks "Donate" button
↓
Transaction submitted to Sui blockchain
↓
Loading spinner during confirmation
↓
Success toast notification
↓
Balance updated, dialog closes
Donation Best Practices
Meaningful Amounts: Even small donations (0.01-1 USDC) are appreciated and help creators know their work resonates.
Include a Message: Adding a personal message makes donations more meaningful to creators.
Transaction Fees: A small fee (~$0.001) applies to cover Sui blockchain costs. 100% of your donation goes to the creator.
Use Cases
| Scenario | Suggested Amount |
|---|---|
| Quick appreciation | 0.5 - 1 USDC |
| Monthly support | 1 - 5 USDC |
| Special content support | 5 - 25 USDC |
| Major milestone celebration | 25 - 100+ USDC |
Revenue Tracking
Creators can view all donations in their earnings dashboard:
// Donation analytics
const totalDonations = donations.reduce((sum, d) => sum + d.amount, 0)
const averageDonation = totalDonations / donations.length
const donationCount = donations.length
Next Steps
- Wallet - Manage your USDC balance
- Memberships - Set up recurring revenue
- Earnings - View your complete revenue dashboard