List Contributions Get a list of all contributions with filtering and pagination.
curl "https://tally.genlayer.com/api/v1/contributions/?user_address=0x1234...&category=builder&ordering=-contribution_date&limit=20"
Query Parameters Filter by user’s Ethereum address
Filter by category: builder, validator, or steward
Filter by contribution type ID
ordering
string
default: "-contribution_date"
Order by field: contribution_date, -contribution_date, points, -points, frozen_global_points, -frozen_global_points
Number of results to return (max 100)
Group consecutive contributions of the same type (for feed views)
Response Show Contribution Object Schema
User information (name, address, profile image)
contribution_type_details
Full contribution type information
Global points (points × multiplier at creation)
Multiplier value when contribution was created
Date when contribution was made
Additional notes or context
Array of evidence objects (URLs, descriptions)
Highlight information if contribution is featured
Mission information if contribution is part of a mission
Timestamp when contribution was recorded
{ "count" : 150 , "next" : "https://tally.genlayer.com/api/v1/contributions/?page=2" , "previous" : null , "results" : [ { "id" : 1 , "user" : 42 , "user_details" : { "id" : 42 , "name" : "Alice Builder" , "address" : "0x1234..." , "profile_image_url" : "https://..." }, "contribution_type" : 5 , "contribution_type_name" : "Smart Contract Deploy" , "contribution_type_details" : { "id" : 5 , "name" : "Smart Contract Deploy" , "slug" : "smart-contract-deploy" , "description" : "Deploy an intelligent contract" , "category" : "builder" , "min_points" : 50 , "max_points" : 200 , "current_multiplier" : 1.5 }, "points" : 100 , "frozen_global_points" : 150 , "multiplier_at_creation" : "1.50" , "contribution_date" : "2024-01-20T10:00:00Z" , "notes" : "First smart contract deployment" , "evidence_items" : [ { "id" : 1 , "description" : "Contract address on testnet" , "url" : "https://explorer.genlayer.com/tx/0xabc..." , "created_at" : "2024-01-20T10:05:00Z" } ], "highlight" : null , "mission" : null , "created_at" : "2024-01-20T10:00:00Z" , "updated_at" : "2024-01-20T10:00:00Z" } ] }
Get Single Contribution Retrieve details for a specific contribution.
curl https://tally.genlayer.com/api/v1/contributions/1/
Response Returns a single contribution object with the same schema as list endpoint.
Submit New Contribution Users can submit contributions for review by stewards.
Authentication Required - You must be authenticated to submit contributions.
curl -X POST https://tally.genlayer.com/api/v1/submissions/ \ -H "Content-Type: application/json" \ --cookie "sessionid=your_session" \ -d '{ "contribution_type": 5, "contribution_date": "2024-01-20T10:00:00Z", "notes": "Deployed my first smart contract", "recaptcha": "03AGdBq...", "mission": 3 }'
Request Body Contribution type ID (must be is_submittable: true)
ISO 8601 date when contribution was made
Description or additional context
Google reCAPTCHA v2 token (required for new submissions only)
Mission ID if contribution is for a specific mission
Validation Rules
Builder contributions require completing the Builder Welcome journey first.Validator contributions require being on the validator waitlist or being a validator.
If mission is provided:
Mission must be active (within start/end dates)
contribution_type is automatically set to mission’s typeCannot override contribution type
Required only for new submissions
Not required when editing existing submissions
Use test keys in development (see .env.example)
Response Submission state: pending, accepted, rejected, or more_info_needed
Whether submission can be edited (true if pending or more_info_needed)
{ "id" : 100 , "user" : 42 , "user_details" : { /* user object */ }, "contribution_type" : 5 , "contribution_type_details" : { /* type object */ }, "contribution_date" : "2024-01-20T10:00:00Z" , "notes" : "Deployed my first smart contract" , "state" : "pending" , "state_display" : "Pending Review" , "staff_reply" : "" , "reviewed_by" : null , "reviewed_at" : null , "evidence_items" : [], "can_edit" : true , "proposed_points" : null , "converted_contribution" : null , "contribution" : null , "mission" : { "id" : 3 , "name" : "Deploy Your First Contract" }, "created_at" : "2024-01-20T10:00:00Z" , "updated_at" : "2024-01-20T10:00:00Z" , "last_edited_at" : null }
Errors { "error" : "You must complete the Builder Welcome journey before submitting builder contributions." }
{ "error" : "This mission has ended." }
{ "recaptcha" : [ "reCAPTCHA verification is required for new submissions." ] }
Get My Submissions Get all submissions for the authenticated user.
curl "https://tally.genlayer.com/api/v1/submissions/my/?state=pending" \ --cookie "sessionid=your_session"
Query Parameters Filter by state: pending, accepted, rejected, more_info_needed
Response Returns paginated list of submission objects.
Update Submission Update a pending or more_info_needed submission.
Submissions can only be edited when can_edit: true (state is pending or more_info_needed).
curl -X PATCH https://tally.genlayer.com/api/v1/submissions/100/ \ -H "Content-Type: application/json" \ --cookie "sessionid=your_session" \ -d '{ "notes": "Updated description with more details" }'
Request Body Same fields as submission creation, but all are optional. Include only fields you want to update.
reCAPTCHA is not required for updates, only for new submissions.
Response Returns the updated submission object with state reset to pending and last_edited_at updated.
Cancel Submission Cancel a pending or more_info_needed submission.
curl -X DELETE https://tally.genlayer.com/api/v1/submissions/100/ \ --cookie "sessionid=your_session"
Response { "message" : "Submission cancelled successfully" }
This is a soft delete. The submission is marked as rejected with “Cancelled by user” note.
Add Evidence to Submission Add evidence items (URLs, descriptions) to a submission.
File uploads are not supported . Evidence must be URLs or text descriptions only.
curl -X POST https://tally.genlayer.com/api/v1/submissions/100/add-evidence/ \ -H "Content-Type: application/json" \ --cookie "sessionid=your_session" \ -d '{ "url": "https://explorer.genlayer.com/tx/0xabc...", "description": "Transaction hash for deployment" }'
Request Body Evidence description (optional)
At least one of url or description must be provided.
Response { "id" : 1 , "description" : "Transaction hash for deployment" , "url" : "https://explorer.genlayer.com/tx/0xabc..." , "created_at" : "2024-01-20T10:05:00Z" }
Get Contribution Highlights Get featured contribution highlights across all types.
curl "https://tally.genlayer.com/api/v1/contributions/highlights/?limit=10&category=builder"
Query Parameters Number of highlights to return
Filter by category: builder, validator, steward, or global
Show only highlights from validator waitlist users
Response [ { "id" : 1 , "title" : "First Smart Contract Deploy" , "description" : "Alice deployed her first intelligent contract on GenLayer testnet" , "contribution" : 1 , "user_name" : "Alice Builder" , "user_address" : "0x1234..." , "user_profile_image_url" : "https://..." , "user_validator" : false , "user_builder" : true , "contribution_type_name" : "Smart Contract Deploy" , "contribution_type_slug" : "smart-contract-deploy" , "contribution_type_category" : "builder" , "contribution_points" : 150 , "contribution_date" : "2024-01-20T10:00:00Z" , "mission_name" : null , "mission_id" : null , "created_at" : "2024-01-20T10:30:00Z" } ]
List Contribution Types Get all available contribution types.
curl "https://tally.genlayer.com/api/v1/contribution-types/?category=builder&is_submittable=true"
Query Parameters Filter by category: builder, validator, or steward
Filter by whether users can submit this type
Response Show Contribution Type Schema
Minimum points for this type
Maximum points for this type
Current global multiplier value
Whether users can submit this type
Example entries for this type
[ { "id" : 5 , "name" : "Smart Contract Deploy" , "slug" : "smart-contract-deploy" , "description" : "Deploy an intelligent contract on GenLayer testnet" , "category" : "builder" , "min_points" : 50 , "max_points" : 200 , "current_multiplier" : 1.5 , "is_submittable" : true , "examples" : [ "First contract deployment" , "DeFi protocol contract" , "NFT marketplace contract" ], "created_at" : "2024-01-01T00:00:00Z" , "updated_at" : "2024-01-15T10:00:00Z" } ]
Get Contribution Type Statistics Get aggregated statistics for contribution types.
curl "https://tally.genlayer.com/api/v1/contribution-types/statistics/?category=builder"
Response [ { "id" : 5 , "name" : "Smart Contract Deploy" , "description" : "Deploy an intelligent contract" , "min_points" : 50 , "max_points" : 200 , "count" : 150 , "participants_count" : 45 , "last_earned" : "2024-03-01T15:00:00Z" , "total_points_given" : 22500 , "current_multiplier" : 1.5 , "is_submittable" : true } ]
Get Top Contributors by Type Get the top 10 contributors for a specific contribution type.
curl https://tally.genlayer.com/api/v1/contribution-types/5/top_contributors/
Response [ { "id" : 42 , "name" : "Alice Builder" , "address" : "0x1234..." , "profile_image_url" : "https://..." , "total_points" : 1500 , "contribution_count" : 15 } ]
Get Recent Contributions by Type Get the last 10 contributions for a specific contribution type.
curl https://tally.genlayer.com/api/v1/contribution-types/5/recent_contributions/
Response Returns an array of contribution objects (lightweight serializer).
Get Contribution Type Highlights Get active highlights for a specific contribution type.
curl "https://tally.genlayer.com/api/v1/contribution-types/5/highlights/?limit=5"
Response Returns an array of highlight objects.
Status Codes Code Meaning Example 200 Success Contribution retrieved 201 Created Submission created 400 Bad Request Invalid contribution_type or missing recaptcha 403 Forbidden Category restriction not met 404 Not Found Contribution type doesn’t exist
Best Practices
Always validate contribution types before submissionCheck category requirements (builder/validator status)Include evidence via URLs or descriptions (no file uploads)Use missions to associate contributions with campaignsHandle reCAPTCHA properly (required for new submissions only)Monitor submission state and respond to more_info_needed