Standard

To ensure seamless integration and interoperability, it is recommended that all Exchange Oracles 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.

Webhook

Used for receiving notifications about various events within the protocol

POST [EXCHANGE_ORACLE_URL]/webhook

Headers

NameTypeDescription

human-signature*

String

Signature used for origin authentication.

Request Body

NameTypeDescription

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.

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

Allows retrieving a list of jobs available to be solved

GET [EXCHANGE_ORACLE_URL]/job

Query Parameters

NameTypeDescription

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 of the fields that should be returned for every available job. Available fields:

job_description, reward_amount, reward_token ,

created_at

escrow_address

String

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

sort_field

String

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

Available fields: chain_id,

job_type,

reward_amount,

created_at

status

Number

Job status: ACTIVE,

COMPLETED,

CANCELED

If no status is provided, return all.

Headers

NameTypeDescription

Authorization*

String

Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

{
    "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
          "job_description": "<Job_Description>",
          "reward_amount": "<Reward_Amount>", 
          "reward_token": "<Reward_Token>",
          "created_at": "<Timestamp>"
        }, 
        ...
    ]
}

Assign job

Request to get a job assigned to a specific user

POST [EXCHANGE_ORACLE_URL]/assignment

Headers

NameTypeDescription

Authorization*

String

Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

Request Body

NameTypeDescription

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>", (Only for COMPLETED, EXPIRED, CANCELED and REJECTED status)
    "expires_at": "<Timestamp>"
}

Get jobs assigned

Allows retrieving a list of jobs assigned to a specific worker

GET [EXCHANGE_ORACLE_URL]/assignment

Query Parameters

NameTypeDescription

status

Enum

Status of the assignment. Values: ACTIVE

VALIDATION

COMPLETED EXPIRED CANCELED

REJECTED

page

Number

Indicates the page number.

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

Id

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

Headers

NameTypeDescription

Authorization*

String

Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

{
    "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>", // (Only for VALIDATION, COMPLETED, EXPIRED, CANCELED and REJECTED status)
            "expires_at": "<Timestamp>"
        }, 
        ...
    ]
}

Resign job

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

POST [EXCHANGE_ORACLE_URL]/assignment/resign

Headers

NameTypeDescription

Authorization*

String

Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

Request Body

NameTypeDescription

assignment_id*

Number

Assignment id

Get assignment stats

Request to get assignment stats for worker that sends the request

GET [EXCHANGE_ORACLE_URL]/stats/assignment

Headers

NameTypeDescription

Authorization*

String

Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

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

Oracle stats

Oracle statistics

GET [EXCHANGE_ORACLE_URL]/stats

It's an open endpoint, but rate limiter should be applied

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

Last updated

Logo

© 2023 HPF. HUMAN Protocol® is a registered trademark