API Reference

Integrate Freshmint's web3 platform into your applications with our comprehensive REST API and SDKs.

API Overview

Authentication

Secure your API requests with wallet signatures or API keys.

Wallet Auth

REST API

Full REST API with JSON responses and standard HTTP methods.

v2.0

Webhooks

Real-time notifications for events, hackathons, and community updates.

Real-time

Authentication

Wallet-Based Authentication

Freshmint uses wallet-based authentication for seamless web3 integration. Users can sign messages with their wallets to authenticate API requests.

Example Request

curl -X POST https://api.freshmint.xyz/v2/auth/wallet \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "signature": "0x...",
    "message": "Sign this message to authenticate with Freshmint API"
  }'

API Key Authentication

For server-to-server communication, use API keys in the Authorization header.

Rate Limits

1000 requests/hour for authenticated users, 100/hour for anonymous requests.

Core Endpoints

Events API

GET /v2/events

List all events with filtering and pagination

POST /v2/events

Create a new event

GET /v2/events/{id}

Get event details

PUT /v2/events/{id}

Update event information

Hackathons API

GET /v2/hackathons

List all hackathons

POST /v2/hackathons

Create a new hackathon

GET /v2/hackathons/{id}/projects

Get hackathon projects

POST /v2/hackathons/{id}/submit

Submit project to hackathon

Communities API

GET /v2/communities

List all communities

POST /v2/communities

Create a new community

GET /v2/communities/{id}/members

Get community members

POST /v2/communities/{id}/join

Join a community

SDKs & Libraries

JavaScript SDK

Official JavaScript/TypeScript SDK with full type support and modern async/await syntax.

Installation

npm install @freshmint/sdk

Quick Start

import { Freshmint } from '@freshmint/sdk';

const client = new Freshmint({
  wallet: signer
});

const events = await client.events.list();

v2.1.0

React Hooks

React hooks for easy integration with Freshmint's features in React applications.

Installation

npm install @freshmint/react

Usage

import { useEvents } from '@freshmint/react';

function EventsList() {
  const { events, loading } = useEvents();
  return <div>{/* render events */}</div>;
}

v1.5.2

Webhooks

Real-time Notifications

Receive real-time notifications when events occur in your Freshmint account. Perfect for building integrations and keeping your systems in sync.

Available Events

• event.created
• event.updated
• hackathon.submission
• community.member_joined
• project.voted

Security

• HMAC signature verification
• Retry logic with exponential backoff
• Webhook secret management
• Event filtering and routing

Example Webhook Payload

{
  "event": "event.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "evt_123",
    "title": "Web3 Builders Meetup",
    "organizer": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6"
  }
}

Getting Started

Get API Key

Generate your API key from the dashboard to start integrating.

Dashboard

Try Examples

Explore our interactive API examples and test endpoints.

API Playground

Join Community

Connect with other developers in our Discord community.

Discord