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

Name	Value
Authorization*	Bearer token (JWT) generated by Reputation Oracle containing `email`, `wallet_address`, etc.

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.

Name

Type

Description

human-signature*

String

Signature used for origin authentication.

Request Body

Name Type Description

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.

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

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.

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

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.

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

Name	Type	Description
Authorization*	String	Bearer token (JWT) generated by Reputation Oracle containing `email`, `wallet_address` , `reputation_network` etc.

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

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

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.

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

Name	Type	Description
Authorization*	String	Bearer token (JWT) generated by Reputation Oracle containing `email`, `wallet_address` , `reputation_network` etc.

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

Name	Type	Description
Authorization*	String	Bearer token (JWT) generated by Reputation Oracle containing `email`, `wallet_address` , `reputation_network` etc.

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

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

Name	Type	Description
Authorization*	String	Bearer token (JWT) generated by Reputation Oracle containing `email`, `wallet_address` , `reputation_network` etc.

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 15 days 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`)