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

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.

200: OK Webhook successfully received

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

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 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

Name	Type	Description
Authorization*	String	Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

200: OK Array of available jobs

{
    "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

Name	Type	Description
Authorization*	String	Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

Request Body

Name	Type	Description
escrow_address*	String	Escrow address
chain_id*	Number	Chain id

200: OK Job assigned

{
    "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

Name	Type	Description
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

Name	Type	Description
Authorization*	String	Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

200: OK Array of assignments

{
    "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>"
        }, 
        ...
    ]
}

Get assignment stats

Request to get assignment stats for worker that sends the request

GET [EXCHANGE_ORACLE_URL]/stats/assignment

Headers

Name	Type	Description
Authorization*	String	Bearer token generated by Reputation Oracle containing email, address, kyc_status and reputation_network

200: OK Stats

{
    "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

200: OK

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