FlowStake API Documentation

Overview

The FlowStake API provides endpoints for activity verification, challenge management, and reward distribution through the Distributed Immutable Activity Ledger (DIAL) system.

Base URL

Production: https://api.flowstake.com
Development: http://localhost:3000

Authentication

All requests must include a valid JWT token:

Authorization: Bearer <token>

Activity Ledger API

Activity Schema

interface Activity {
  id: string;
  user_id: string;
  strava_activity_id: string;
  type: string;
  distance: number;
  duration: number;
  elevation_gain: number;
  start_date: string;
  verified: boolean;
  created_at: string;
  updated_at: string;
  ipfs_hash?: string;
  attestation_uid?: string;
  challenge?: {
    id: string;
    type: string;
    challenge_type: 'solo' | 'group';
    participants: {
      id: string;
      participant_id: string;
      ens_name?: string;
      eth_address?: string;
      completion_status: 'pending' | 'completed' | 'failed';
      distance_completed: number;
      time_completed: number;
      profiles?: {
        name: string | null;
        avatar_url: string | null;
      };
    }[];
  };
}

Trackpoint Schema

interface TrackPoint {
  timestamp: string;
  latitude: number;
  longitude: number;
  elevation: number;
  distance: number;
  heartRate?: number;
  cadence?: number;
  power?: number;
}

Activity Metadata Schema

interface ActivityMetadata {
  type: string;
  distance: number;
  duration: number;
  elevationGain: number;
  startDate: string;
  device?: string;
  athlete?: string;
}

EAS Schema

struct ActivityAttestation {
    address athlete;
    uint256 timestamp;
    string activityType;
    uint256 distance;
    uint256 duration;
    bytes32 proof;
}

Endpoints

Create Activity Attestation

POST /api/activities/attest
Content-Type: application/json
Authorization: Bearer <token>

{
  "activity": {
    "type": "running",
    "distance": 5000,
    "duration": 1800,
    "elevationGain": 100,
    "startDate": "2024-03-27T10:00:00Z"
  },
  "trackpoints": [
    {
      "timestamp": "2024-03-27T10:00:00Z",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "elevation": 10,
      "distance": 0
    }
  ]
}

Get Activity Records

GET /api/activities
Authorization: Bearer <token>

Verify Activity

POST /api/activities/:id/verify
Authorization: Bearer <token>

{
  "verifier": "0x...",
  "signature": "0x..."
}

Proof of Activity as a Stake

Challenge Schema

interface Challenge {
  id: string;
  creator_id: string;
  type: 'individual' | 'team' | 'lastStanding' | 'relay';
  activity_type: 'running' | 'cycling' | 'walking' | 'swimming';
  token_type: 'ETH' | 'USDC' | 'FST';
  stake_amount: number;
  target_distance?: number;
  target_time?: number;
  start_date: string;
  end_date: string;
  min_participants?: number;
  max_participants?: number;
  status: 'pending' | 'active' | 'completed' | 'cancelled';
  description?: string;
}

Create Challenge

POST /api/challenges
Content-Type: application/json
Authorization: Bearer <token>

{
  "type": "individual",
  "activityType": "running",
  "tokenType": "ETH",
  "stakeAmount": 0.1,
  "targetDistance": 5000,
  "startDate": "2024-04-01T00:00:00Z",
  "endDate": "2024-04-07T23:59:59Z"
}

Join Challenge

POST /api/challenges/:id/join
Authorization: Bearer <token>

{
  "ensName": "athlete.eth",
  "ethAddress": "0x..."
}

Update Challenge Progress

PUT /api/challenges/:id/progress
Authorization: Bearer <token>

{
  "distance": 2500,
  "time": 900
}

Smart Contract Integration

Activity Verifier Contract

interface IActivityVerifier {
    function verifyActivity(
        bytes32 activityId,
        uint256 timestamp,
        string activityType,
        uint256 distance,
        uint256 duration,
        bytes32 proof
    ) external returns (bool);

    function getVerification(bytes32 activityId) external view returns (
        bool verified,
        address verifier,
        uint256 timestamp
    );

    event ActivityVerified(
        bytes32 indexed activityId,
        address indexed verifier,
        uint256 timestamp
    );
}

Challenge Contract

interface IFlowstakeChallenge {
    function createChallenge(
        ActivityType activityType,
        TokenType tokenType,
        uint256 stakeAmount,
        uint256 targetDistance,
        uint256 targetTime,
        uint256 startDate,
        uint256 duration
    ) external payable returns (uint256);

    function joinChallenge(uint256 challengeId) external payable;
    
    function submitActivity(
        uint256 challengeId,
        bytes32 activityId,
        uint256 distance,
        uint256 time
    ) external;

    function claimRewards(uint256 challengeId) external;
}

Error Handling

All API endpoints return standard HTTP status codes:

• 200: Success
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 500: Internal Server Error

Error Response Format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {}
  }
}

Rate Limiting

• 100 requests per minute per IP
• 1000 requests per hour per user
• Burst limit: 10 requests per second

IPFS Integration

Activities are stored on IPFS with the following structure:

{
  "metadata": {
    "type": "running",
    "distance": 5000,
    "duration": 1800,
    "elevationGain": 100,
    "startDate": "2024-03-27T10:00:00Z",
    "device": "Garmin Forerunner 945",
    "athlete": "0x..."
  },
  "trackpoints": [
    {
      "timestamp": "2024-03-27T10:00:00Z",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "elevation": 10,
      "distance": 0,
      "heartRate": 140,
      "cadence": 180,
      "power": 250
    }
  ],
  "proof": {
    "hash": "0x...",
    "signature": "0x...",
    "attestationUid": "0x..."
  }
}