Skip to main content
The Shade Agent Framework is experimental and contains known critical vulnerabilities.It must not be used in production or on mainnet and is intended solely for testing and non-critical use on testnet.No representations or warranties are made regarding security, correctness, or fitness for any purpose. Use of this software is entirely at your own risk.A production-ready version of the framework is currently in development.
In this section, we’ll walk you through deploying a Shade Agent. The Shade Agent Framework abstracts the complexities of creating an agent by removing TEE specific code and handling the deployment of the agent contract under the hood. The template we’re using is a simple Shade Agent built with Hono and written in TypeScript that acts as a verifiable ETH price oracle. It fetches the price of ETH from two different APIs, takes the average, and then pushes the price to an Ethereum contract.

Try the live demo

See the ETH price oracle agent in action
We’ll cover two deployment scenarios:
  1. Local Development: Running the agent locally for rapid testing and development.
  2. TEE Deployment: Running the agent in a real Trusted Execution Environment (TEE).

​
Prerequisites

1

Install NEAR and Shade Agent tooling

# Install the NEAR CLI
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh

# Install the Shade Agent CLI
npm i -g @neardefi/shade-agent-cli
2

Create a NEAR testnet account

Create a NEAR testnet account and record the account name and seed phrase:
export ACCOUNT_ID=example-name.testnet
near account create-account sponsor-by-faucet-service $ACCOUNT_ID autogenerate-new-keypair save-to-keychain network-config testnet create
Replace example-name.testnet with a unique account ID.
3

Set up Docker

If you haven’t already:
  • Install Docker for Mac or Linux and create an account.
  • Log in to Docker, using docker login for Mac or sudo docker login for Linux.
4

Create a Phala Cloud account

Set up a free Phala Cloud account at https://cloud.phala.network/register, then get an API key from https://cloud.phala.network/dashboard/tokens.
Phala Cloud is a cloud service that supports hosting applications in a TEE. It makes it easy to run an agent in TEE.

​
Setup

1

Clone the template

git clone https://github.com/NearDeFi/shade-agent-template
cd shade-agent-template
2

Configure environment variables

Rename the .env.development.local.example file to .env.development.local and configure your environment variables.
3

Start Docker

sudo systemctl start docker
4

Install dependencies

npm i

​
Local development

1

Configure contract ID

Make sure the NEXT_PUBLIC_contractId prefix is set to ac-proxy. followed by your NEAR accountId.
2

Run the Shade Agent CLI

In one terminal, run:
shade-agent-cli
The CLI on Linux may prompt you to enter your sudo password.
3

Start your app

In another terminal:
npm run dev
Your app will start on http://localhost:3000

​
TEE deployment

1

Configure contract ID

Change the NEXT_PUBLIC_contractId prefix to ac-sandbox. followed by your NEAR accountId.
2

Run the Shade Agent CLI

shade-agent-cli
The CLI on Linux may prompt you to enter your sudo password.The last URL the CLI outputs is the URL of your app. If your application is not working, head over to your App on the Phala Dashboard and review the logs.After deploying to Phala Cloud, monitor your deployments and delete unused ones to avoid unnecessary costs. You can manage your deployments from the dashboard.

​
Interacting with the agent

You can interact with your agent via the APIs directly or via a lightweight frontend contained in this repo.
For Phala deployments, swap localhost:3000 for your deployment URL.
1

Get the Agent account ID and its balance

http://localhost:3000/api/agent-account
2

Get the derived Ethereum Sepolia price pusher account

Get the account ID and its balance (you will need to fund this account):
http://localhost:3000/api/eth-account
3

Send a transaction through the agent

Update the price of ETH:
http://localhost:3000/api/transaction

​
Understanding the template

The template is a simple Shade Agent that acts as a verifiable ETH price oracle. The project has three different APIs:

​
1. Agent account

This API fetches the agent’s NEAR account ID and its balance by using the agentAccountId and agent("getBalance") functions from the shade-agent-js library.

​
2. ETH account

This API returns the Ethereum Sepolia account that the Shade Agent uses to update the price of Ethereum in the Sepolia contract. This API is used so the user knows which account to fund for gas.

​
3. Transaction

This is where the core logic of the agent is defined. When this API is called, the agent will build and sign a transaction.

​
Signing transactions

In the transaction API route, the requestSignature function from the shade-agent-js library is used to sign a transaction. First, the agent retrieves the price of ETH by querying two different APIs and calculating the average. Next, the agent builds the transaction payload to be signed using the chainsig.js library:
  1. Derive the Ethereum address that will be sending the transaction. This function takes the agent contract account ID and a path. The path can be any string you like - different paths will derive different addresses.
  2. Create the data. This is what action we’re performing, in this case, a function call to update the price in the contract.
  3. Build the transaction and the transaction payload by inputting the derived address, the target Ethereum smart contract, and the data.
Once we have the payload (also known as the hash), we can call the requestSignature function to sign the transaction. We specify the keyType as Ecdsa as we’re signing for a blockchain that uses the secp256k1 signature scheme. The result is the signature. We then attach the signature to the Ethereum transaction and broadcast it to the target network.

​
Using different chains

The template sets up a chain adapter for Ethereum Sepolia using the chainsig.js library. This library allows you to easily construct transaction payloads to be signed by the agent. You can set up chain adapters for a variety of chains, including EVM, Bitcoin, NEAR, Solana, SUI, XRP, Cosmos, and more to allow your agent to interact with multiple different chains. You can see a full list of the chains currently supported here. If you are using a chain that uses the ed25519 signature scheme (NEAR, Solana, SUI, Aptos, etc.), you should specify the keyType as Eddsa when calling requestSignature.

​
Next steps

Framework Overview

Dive deeper into the framework to understand the core concepts needed for building production-ready Shade Agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us