API Reference

Client Automation Registration

POST /v1/automations/executor

This endpoint can be used by executors create an automation that users can subscribe to

Query Params

Field name	Type	Description
executorAddress	string	address of executor that is creating the automation

Field name

Type

Description

executorAddress

string

address of executor that is creating the automation

Request Body

Field name	Type	Description
config	Config	Configuration specifications for client automation. Check the format for the type below
executor	string	Address of executor that runs the automation
signature	string	Signature of the client configuration message signed by the executor. Check example & types here
chainId	integer	Chain ID to create client automation on
timestamp	integer	Current timestamp. Must match the timestamp that is signed by executor
executorMetadata	JSON	Arbitrary metadata JSON of data that the executor wishes to accept from users at time of subscription

Field name

Type

Description

config

Config

Configuration specifications for client automation. Check the format for the type below

executor

string

Address of executor that runs the automation

signature

string

Signature of the client configuration message signed by the executor. Check example & types here

chainId

integer

Chain ID to create client automation on

timestamp

integer

Current timestamp. Must match the timestamp that is signed by executor

executorMetadata

JSON

Arbitrary metadata JSON of data that the executor wishes to accept from users at time of subscription

Config

Field name	Type	Description
feeInBPS	integer	fees collected by the automation in BPS; MAX_BPS=4
feeReceiver	string	address of the automation client's fee receiver
limitPerExecution	bool	boolean denoting if the user should limit the input tokens being pulled by executor per execution or for a specific duration of time; true if the limit is per execution
feeToken	string	address of the token to collect fees in
inputTokens	string[]	list of addresses of input tokens for the automation
hopAddresses	string[]	list of whitelisted addresses through which the token is allowed to be transferred during the automations

Field name

Type

Description

feeInBPS

integer

fees collected by the automation in BPS; MAX_BPS=4

feeReceiver

string

address of the automation client's fee receiver

limitPerExecution

bool

boolean denoting if the user should limit the input tokens being pulled by executor per execution or for a specific duration of time; true if the limit is per execution

feeToken

string

address of the token to collect fees in

inputTokens

string[]

list of addresses of input tokens for the automation

hopAddresses

string[]

list of whitelisted addresses through which the token is allowed to be transferred during the automations

Example

{
  "config": {
    "feeInBPS": 100,
    "feeReceiver": "0x00Ab3bCd63A3938031C27B122ec2b7f87EC0bA47",
    "feeToken": "0x00Ab3bCd63A3938031C27B122ec2b7f87EC0bA47",
    "limitPerExecution": true,
    "inputTokens": [
      "0xAb3BCd63A3938031c27b122Ec2B7F87Ec0Ba472A",
      "0xAb3BCd63A3938031c27b122Ec2B7F87Ec0Ba472B"
    ],
    "hopAddresses": [
      "0xAb3BCd63A3938031c27b122Ec2B7F87Ec0Ba472D",
      "0xAb3BCd63A3938031c27b122Ec2B7F87Ec0Ba472C"
    ]
  },
  "executor": "0xAb3BCd63A3938031c27b122Ec2B7F87Ec0Ba472A",
  "signature": "0x4dad6b013c18d43e41a38c91c8df5833eb309300c700a03440cfc4bea2ee15d54a123c228bfb21b652bed59e1a5ed67e147163e7ab81df4d83a8195dfdf051131c",
  "chainId": 42161,
  "timestamp": 1,
  "executorMetadata": {
    "id": "test-dapp",
    "name": "test",
    "logo": "test",
    "metadata": {}
  }
}

Response

The response contains all the config fields passed by the user in request, along with the ID of the successfully created client automation -

{
  "data": {
    "config": {
      "feeInBPS": 100,
      "feeReceiver": "0x00ab3bcd63a3938031c27b122ec2b7f87ec0ba47",
      "limitPerExecution": true,
      "feeToken": "0x00ab3bcd63a3938031c27b122ec2b7f87ec0ba47",
      "inputTokens": [
        "0xab3bcd63a3938031c27b122ec2b7f87ec0ba472a",
        "0xab3bcd63a3938031c27b122ec2b7f87ec0ba472b"
      ],
      "hopAddresses": [
        "0xab3bcd63a3938031c27b122ec2b7f87ec0ba472d",
        "0xab3bcd63a3938031c27b122ec2b7f87ec0ba472c"
      ]
    },
    "executor": "0xab3bcd63a3938031c27b122ec2b7f87ec0ba472a",
    "signature": "0x4dad6b013c18d43e41a38c91c8df5833eb309300c700a03440cfc4bea2ee15d54a123c228bfb21b652bed59e1a5ed67e147163e7ab81df4d83a8195dfdf051131c",
    "chainId": 42161,
    "timestamp": 1,
    "executorMetadata": {
      "id": "test-dapp",
      "name": "test",
      "logo": "test",
      "metadata": {}
    },
    "id": "239a574e-96b6-4168-969b-2f806bfb55fc",
    "status": 0
  }
}

{
  "data": {
    "error": "an error occurred"
  }
}

Query Automation Subscribers

GET /v1/automations/executor/:registryID/subscriptions

This endpoint can be used be executors to get a list of subscribers to a given registryID

Query Params

Field name	Type	Description
registryID	string	ID of the client's automation registry. (can be retrieved from response of automation registration)

Field name

Type

Description

registryID

string

ID of the client's automation registry. (can be retrieved from response of automation registration)

Response

Response contains list of all subscribers and their subscription configuration & metadata-

{
	"data": [
        {
            "chainId": 42161,
            "commitHash": "0x7f8c52bd5e691fd15398eb8097585d1572152defeb2b42e2f34c6f4b20cea15e",
            "createdAt": "2024-07-31T08:25:48.469066Z",
            "duration": 0,
            "feeAmount": "0",
            "feeToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
            "id": "50ad43f1-b44f-442b-b7e5-e5df041b223a",
            "metadata": {
                "amount": "1000000000000000",
                "chains": [
                    8453,
                    34443
                ],
                "minAmount": "150000000000000",
                "refuelAddress": "0xAb3BCd63A3938031c27b122Ec2B7F87Ec0Ba472A"
            },
            "registryId": "259d6ce7-1008-43dc-8f48-f7c53354d194",
            "status": 2,
            "subAccountAddress": "0x3e26fe336ebae6135a3ae1600f13a01a1d2510c4",
            "tokenInputs": {
                "0x0000000000000000000000000000000000000000": "2000000000000000"
            },
            "tokenLimits": {
                "0x0000000000000000000000000000000000000000": "0.001"
            }
        }
    ],
    ...
}

{
  "data": {
    "error": "an error occurred"
  }
}

Validate Executable Task

POST /v1/automations/tasks/validate/:chainId

This endpoint can be used by executors to pass an executable for a subscriber's account and validate if it complies with the policy

Query Params

Field name	Type	Description
chainId	string	Chain ID to validate the executable on

Field name

Type

Description

chainId

string

Chain ID to validate the executable on

Request Body

Field name	Type	Description
subaccount	string	Address of the subscriber subAccount to validate the executable task on
executor	string	Address of the executor
executorSignature	string	Signature of executor, signing the ExecutionParams digest. Check example & types here
executable	Executable	Params of the executable task to validate. Check the format for the type below

Field name

Type

Description

subaccount

string

Address of the subscriber subAccount to validate the executable task on

executor

string

Address of the executor

executorSignature

string

Signature of executor, signing the ExecutionParams digest. Check example & types here

executable

Executable

Params of the executable task to validate. Check the format for the type below

Executable

Field name Type Description

Field name	Type	Description
callType	integer	type of call to make; CALL(0), DELEGATECALL(1), or STATICCALL(2)
to	string	address of the target to execute on
value	integer	amount of ETH to transfer from subscriber to `to`
data	string	calldata to execute on `to`

callType

integer

type of call to make; CALL(0), DELEGATECALL(1), or STATICCALL(2)

string

address of the target to execute on

value

integer

amount of ETH to transfer from subscriber to to

data

string

calldata to execute on to

Example

{
  "task": {
    "subaccount": "[subAccount-address]",
    "executor": "[executor-address]",
    "executorSignature": "[executor-signature]",
    "executable": {
      "callType": "[call-type]",
      "to": "[target-address]",
      "value": 0,
      "data": "[data]"
    }
  }
}

Response

Response contains the policy signature required for module execution of the automation on successful validation-

{
  "data": {
    "expiry": 1713777104,
    "policySignature": "[policy-signature]"
  }
}

{
  "data": {
    "error": "an error occurred"
  }
}

Validate & Execute an Executable Task

POST /v1/automations/tasks/execute/:chainId

This endpoint can be used by executors to pass an executable for a subscriber's account and execute it using Console Relayer, if it complies with the policy

Query Params

Field name	Type	Description
chainId	string	Chain ID to execute the executable on

Field name

Type

Description

chainId

string

Chain ID to execute the executable on

Request Body

Field name	Type	Description
subaccount	string	Address of the subscriber subAccount to validate the executable task on
executor	string	Address of the executor
executorSignature	string	Signature of executor, signing the ExecutionParams digest. Check example & types here
executable	Executable	Params of the executable task to validate. Check the format for the type below
webhook (optional)	string	Webhook URL to get status updates on from relayer

Field name

Type

Description

subaccount

string

Address of the subscriber subAccount to validate the executable task on

executor

string

Address of the executor

executorSignature

string

Signature of executor, signing the ExecutionParams digest. Check example & types here

executable

Executable

Params of the executable task to validate. Check the format for the type below

webhook (optional)

string

Webhook URL to get status updates on from relayer

Executable

Field name Type Description

Field name	Type	Description
callType	integer	type of call to make; CALL(0), DELEGATECALL(1), or STATICCALL(2)
to	string	address of the target to execute on
value	integer	amount of ETH to transfer from subscriber to `to`
data	string	calldata to execute on `to`

callType

integer

type of call to make; CALL(0), DELEGATECALL(1), or STATICCALL(2)

string

address of the target to execute on

value

integer

amount of ETH to transfer from subscriber to to

data

string

calldata to execute on to

Example

{
  "task": {
    "subaccount": "[subAccount-address]",
    "executor": "[executor-address]",
    "executorSignature": "[executor-signature]",
    "executable": {
      "callType": "[call-type]",
      "to": "[target-address]",
      "value": "[value]",
      "data": "[data]"
    }
  },
  "webhook": "https://3rdParty.client.fi/v1/automations/tasks" // optional
}

Response

Response contains taskId of the executed task, that can be used for polling of status-

{
  "data": {
    "taskId": "[taskId]"
  }
}

{
  "data": {
    "error": "an error occurred"
  }
}

Poll Executed Task Status

GET /v1/relayer/tasks/status/:taskId

Query Params

Field name	Type	Description
taskId	string	ID of the executed task. (can be retrieved from the response of the validate & execute endpoint)

Field name

Type

Description

taskId

string

ID of the executed task. (can be retrieved from the response of the validate & execute endpoint)

Response

Response contains the task's metadata and it's current status-

{
  "data": {
    "taskId": "[task-id]",
    "metadata": {
      "request": {
        "taskId": "[task-id]",
        "to": "[to]",
        "callData": "[call-data]",
        "requestedAt": 0,
        "timeout": 0,
        "signer": "[signer]",
        "chainID": "[chain-id]",
        "useSafeGasEstimate": false,
        "maxGasLimit": 0,
        "enableAccessList": false,
        "backendId": "[backend-id]",
        "webhook": "[webhook-url]"
      },
      "response": {
        "isSuccessful": false,
        "error": "[error]",
        "transactionHash": null
      }
    },
    "outputTransactionHash": null,
    "status": "[status]",
    "createdAt": "0001-01-01T00:00:00Z"
  }
}

{
  "data": {
    "error": "an error occurred"
  }
}

PreviousAutomation API Example

Last updated 26 days ago