Standard

To ensure seamless integration and interoperability, it is recommended that all Exchange Oracles that want their jobs listed in HUMAN App adhere to certain endpoint standards.

The interaction between the annotation tool and the Exchange Oracle is unique for each annotation tool, and therefore, it is not outlined in this document.

Registration (`OPTIONAL`)

POST /register

Used for registering a user in Exchange Oracle. If an additional registration process is needed, Exchange Oracle operator must store two additional parameters in KVStore:

registration_needed: true
registration_instructions: URL

Headers

Name

Value

Authorization*

Bearer token (JWT) generated by Reputation Oracle containing email, wallet_address, etc.

Response

{
  "email": string,
  "wallet_address": string
}

{
  "error": "Invalid request"
}

Webhook

POST /webhook

Used for receiving notifications about various events within the Protocol

Headers

Name

Type

Description

human-signature*

String

Signature used for origin authentication.

Request Body

Name

Type

Description

escrow_address*

String

The address of the escrow involved in the event.

chain_id*

Number

The identifier of the chain where the escrow exists.

event_type*

Enum

The type of event, which can be one of the following:

escrow_created: Indicates the creation of a new escrow.

escrow_canceled: Indicates the cancellation of an escrow.

submission_rejected: Indicates that a submission provided was refused.

event_data

Object

It gives information about the event, like refusal reason for an invalid submission.

{
    "id": string
}

escrow_created

{
    "escrow_address": "",
    "chain_id": "137",
    "event_type": "escrow_created"
}

escrow_canceled

{
    "escrow_address": "",
    "chain_id": "137",
    "event_type": "escrow_canceled"
}

submission_rejected

{
    "escrow_address": "",
    "chain_id": "137",
    "event_type": "submission_rejected",
    "event_data": {
        "assignments": [
            {
                "assignment_id": "",
                "reason": "" (optional)
            },   
            {
                "assignment_id": "",
                "reason": "" (optional)
            },
        ]  
    }
}

Get jobs list

GET /job

Allows retrieving a list of jobs available to be solved

Query Parameters

Name

Type

Description

chain_id

Number

Chain ID from which the user wants to get the list of jobs. If empty return all chains.

page_size

Number

Specifies the number of items to include in each page. Max 10. Default 5.

page

Number

Indicates the page number. Default 0.

sort

String

Specifies the order in which the items are returned based on sort_field. Values: asc, desc. Default asc.

job_type

String

Job type

fields

String[]

List (comma separated values) of the fields that should be returned for every available job. Available fields:

job_description, reward_amount, reward_token ,

created_at, updated_at

escrow_address

String

Escrow address. Should be used in case requester wants to return only details about the specific escrow.

created_after

String

Filter to retrieve jobs created after the specified date.

updated_after

String

Filter to retrieve jobs updated after the specified date.

sort_field

String

Field used for sorting returned results. Default value: created_at.

Available fields: chain_id, job_type, reward_amount, created_at, updated_at

status

Number

Job status: active,

completed,

canceled

If no status is provided, return all.

Headers

Name

Type

Description

Authorization*

String

Bearer token (JWT) generated by Reputation Oracle containing email, wallet_address (optional, not required if role is human_app) etc.

{
    "page": number,
    "page_size": number,
    "total_pages": number,
    "total_results": number,
    "results": [
        {
          // Default schema in case `fields` is not defined
          "escrow_address": "<Address>", // Always to be returned
          "chain_id": "<Chain_Id>", // Always to be returned
          "job_type": "<Job_Type>", // Always to be returned
          "status": "<Status>", // Always to be returned
          "qualifications": string[], // Always to be returned (Might be empty)
          "job_description": "<Job_Description>",
          "reward_amount": "<Reward_Amount>", 
          "reward_token": "<Reward_Token>",
          "created_at": "<Timestamp>",
          "updated_at": "<Timestamp>",
        }, 
        ...
    ]
}

Assign job

POST /assignment

Request to get a job assigned to a specific user

Headers

Name

Type

Description

Authorization*

String

Bearer token (JWT) generated by Reputation Oracle containing email, wallet_address , reputation_network etc.

Request Body

Name

Type

Description

escrow_address*

String

Escrow address

chain_id*

Number

Chain id

{
    "assignment_id": "<Assignment_Id>",
    "escrow_address": "<Escrow_Address>",
    "chain_id": "<Chain_Id>",
    "job_type": "<Job_Type>",
    "url": "<Url>", (Only for active status)
    "status": "<Status>",
    "reward_amount": "<Reward_Amount>",
    "reward_token": "<Reward_Token>",
    "created_at": "<Timestamp>",
    "updated_at": "<Timestamp>",
    "expires_at": "<Timestamp>"
}

Get jobs assigned

GET /assignment

Allows retrieving a list of jobs assigned to a specific worker

Query Parameters

Name

Type

Description

status

Enum

Status of the assignment. Values: active

validation

completed expired canceled

rejected

page

Number

Indicates the page number. Default 0.

sort

String

Specifies the order in which the items are returned based on sort_field. Values: asc, desc. Default asc.

page_size

Number

Specifies the number of items to include in each page. Max value: 10. Default: 5

escrow_address

String

Escrow address

chain_id

Number

Chain id

assignment_id

String

Assignment id. Should be used in case requester wants to return only details about the specific assignment.

sort_field

String

Field used for sorting returned results. Default value: created_at.

Available fields: chain_id,

job_type,

status,

reward_amount,

created_at,

expires_at (should return active assignments)

job_type

String

Job type

created_after

String

Filter to retrieve assignments created after the specified date.

updated_after

String

Filter to retrieve assignments updated after the specified date.

Headers

Name

Type

Description

Authorization*

String

Bearer token (JWT) generated by Reputation Oracle containing email, wallet_address , reputation_network etc.

{
    "page": number,
    "page_size": number,
    "total_pages": number,
    "total_results": number,
    "results": [
        {
            "assignment_id": "<Assignment_Id>", 
            "escrow_address": "<Escrow_Address>",
            "chain_id": "<Chain_Id>",
            "job_type": "<Job_Type>",
            "url": "<Url>", // (Only for active status)
            "status": "<Status>", 
            "reward_amount": "<Reward_Amount>",
            "reward_token": "<Reward_Token>",
            "created_at": "<Timestamp>",
            "updated_at": "<Timestamp>",
            "expires_at": "<Timestamp>"
        }, 
        ...
    ]
}

Resign job

POST /assignment/resign

This endpoint should be called when a user who has been assigned a job decides they no longer want to solve it.

Headers

Name

Type

Description

Authorization*

String

Bearer token (JWT) generated by Reputation Oracle containing email, wallet_address , reputation_network etc.

Request Body

Name

Type

Description

assignment_id*

String

Assignment id

Get assignment stats

GET /stats/assignment

Request to get assignment stats for the worker that sends the request.

Headers

Name

Type

Description

Authorization*

String

Bearer token (JWT) generated by Reputation Oracle containing email, wallet_address , reputation_network etc.

{
    "assignments_total": <Number>,
    "submissions_sent": <Number>,
    "assignments_completed": <Number>,
    "assignments_rejected": <Number>,
    "assignments_expired": <Number>
}

Oracle stats

GET /stats

Oracle statistics

This is an open endpoint, but rate limiter should be applied

{
    "workers_total": <Number>,
    "assignments_completed": <Number>,
    "assignments_rejected": <Number>,
    "assignments_expired": <Number>,
    "escrows_processed": <Number>,
    "escrows_active": <Number>,
    "escrows_cancelled": <Number>
}

PreviousExchange Oracle NextRecording Oracle

Last updated 1 month ago

Registration (OPTIONAL)

Webhook

Headers

Request Body

escrow_created

escrow_canceled

submission_rejected

Get jobs list

Query Parameters

Headers

Assign job

Headers

Request Body

Get jobs assigned

Query Parameters

Headers

Resign job

Headers

Request Body

Get assignment stats

Headers

Oracle stats

Registration (`OPTIONAL`)