Space3 Federated API for Partners

1. Introduction

This guide is for partners who want to integrate their systems with Space3's mission system. It defines the communication interface between Space3 and your platform.

Purpose

This API allows you to verify missions completed by users on your platform and receive relevant user data from Space3. This data can be used to reward users for completing missions or track their progress.

2. API Overview

Space3 uses a federated API approach, enabling communication between your system and Space3's mission system. Here's a breakdown of the request and response formats:

1. Request

• Method: HTTP GET

• Purpose: Retrieve user data from Space3 when a user triggers mission verification on Space3 platform.

Request Parameters

Space3 sends the following user data in the request URL:

• fromDate & toDate: Auto-filled ISO date string as request queries, time-bounded of the verifying.

• UID: Unique identifier for the Space3 user (string, optional).

• Email: User's email address linked to their Space3 account (string, optional).

• Wallet: User's EVM wallet address linked to Space3 (string, optional).

• Discord ID: User's Discord ID linked to Space3 (string, optional).

• X ID (Twitter): User's X ID (Twitter) linked to Space3 (string, optional).

• TelegramID : Coming soon...

Request Pattern Example:

You can design an API to support User data fulfilling any were in the URL.

https://partner.com/space3/playing/{Email}/1?email={Email}&wallet={wallet}

In this example, the {Email} value can be fulfilled as a path variable (first placeholder) or a query parameter value (second placeholder).

The information of a user triggered the verifying:

1. UID: 660acc89142ce43bb232a3e5

2. Email: [e-mail]

3. Wallet: 0x082FDe0469dB49B39a95276c894bB8f386BF3dDD

Request fulfilled:

https://partner.com/space3/playing/[e-mail]/1?email=[e-mail]&wallet=0x082FDe0469dB49B39a95276c894bB

Explanation:

Space3 replaces placeholders ({Email} and {wallet}) in the request URL with the actual user data.

2. Response

The response format depends on the type of mission being verified:

• Simple Tasks: For tasks that can be completed once, respond with a simple JSON object containing a single boolean field: success.

Success Example:

Status code: 200

{
    "success": true
}

Failure Example:

Status code: 200

{
    "success": false
}

• Accumulative Tasks: For tasks with ongoing progress, respond with a JSON array containing objects for each user achievement. Each object has two fields:

  • timestamp: The UTC timestamp (string) of when the user achieved a mission target.

  • completedTimes: The number of times (integer) the user has completed the task as of the timestamp. The value must be greater than 0.

  Response Example:

  [
      { "timestamp": "2023-12-04T07:09:03.186Z", "completedTimes": 9 },
      { "timestamp": "2023-12-05T07:09:03.186Z", "completedTimes": 8 }
  ]