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

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

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

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 -

Success (200)

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

Error (500)

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

Response

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

Success (200)

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

Error (500)

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

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

• Executable

  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

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-

Success (200)

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

Error (500)

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

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

Executable

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

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-

Success (200)

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

Error (500)

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

Response

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

Success (200)

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