Skip to content
notch
Get $NOTCH

// docs

From blocks to a running script.

Three steps: build it, read it, run it. The whole thing takes a few minutes the first time.

// 01 build

Make the stack.

Open the builder. A script is one trigger on top, which decides when things happen, and a stack of blocks under it, which decides what happens, top to bottom.

Drag a block from the list into the stack, or click it to add it at the end. Fill in the blanks. Blocks that are missing something turn red and say what they need. When nothing is red, the script appears on the right.

Or type what you want in the prompt box. A prompt costs $0.25, paid in $NOTCH from your wallet at the current price: connect a wallet, press the button, approve the transfer. Asking for a new script and changing the current one cost the same. How paying works.

// 02 values

Blanks and variables.

> cat blanks.txt
a number0.5, or a variable name
an addressbase58, or me
a tokenSOL USDC USDT JUP BONK
any other tokenits mint address
a messagetext with {name}

A variable is a named box. The green blocks fill one: set balance to SOL balance of me reads your balance and keeps it as balance.

After that, any number blank can say balance instead of a number, and any message can say {balance} to print it.

Some triggers fill a variable for you: the price trigger sets price, the balance trigger sets balance, the wallet trigger sets signature.

me is the wallet the script runs with. Amounts are in whole tokens: 0.1 SOL is written 0.1.

// 03 run

Run it on your machine.

You need Node.js 20 or newer. Download the script from the builder into an empty folder, open a terminal there, then:

# once: install what the script imports (the exact line is at the top of your file)$ npm install @solana/web3.js @solana/spl-token bs58 tsx
# a script that only reads or alerts needs nothing else$ npx tsx sol-price-alert.ts
# a script that signs: dry run first, it simulates and prints what would happen$ SECRET_KEY=... npx tsx hourly-dca.ts# when the dry run looks right, send for real$ SECRET_KEY=... DRY_RUN=false npx tsx hourly-dca.ts
> env
SECRET_KEYbase58 or JSON array
DRY_RUNfalse to send for real
RPC_URLyour RPC, optional

Use a fresh wallet. Create a new wallet for the script, fund it with only what the script needs, and export that wallet's key. Never use the key of your main wallet.

Never paste a key into a website, this one included. The key goes in your terminal, on your machine, and nowhere else.

The default public RPC is slow and rate limited. For anything that runs all day, set RPC_URL to an endpoint from an RPC provider.

Triggers that repeat keep the script running until you stop it with Ctrl+C. To keep one running after you close the terminal, use a process manager or a small server.

// reference

Every block.

> ls blocks/triggers(!)
  • when the script startsRuns the stack once, then exits.
  • every [n] [unit]Runs the stack now, then again on a fixed interval.
  • when [mint] price goes [dir] [usd] USDChecks the price every 15 seconds and runs the stack each time it crosses the level. Sets price.
  • when SOL balance of [address] changesSubscribes to the account and runs the stack on every change. Sets balance, in SOL.
  • when [address] makes a transactionRuns the stack for every successful transaction that mentions the address. Sets signature.
> ls blocks/actions[>]
  • log [message]Prints a line to the terminal.
  • send [amount] SOL to [to]Transfers SOL from the script's wallet. Signs a transaction.
  • send [amount] [mint] to [to]Transfers a token from the script's wallet. Creates the recipient's token account if it is missing. Signs a transaction.
  • swap [amount] [from] for [to] with [slippage] % max slippageSwaps through the Jupiter aggregator. The amount is in units of the token you sell. Signs a transaction.
  • post [message] to [url]Sends the message to a webhook URL. Works with Discord and Slack webhooks as they are.
  • wait [seconds] secondsPauses the stack.
  • stop the scriptEnds the script for good, including its trigger.
> ls blocks/data[=]
  • set [var] to SOL balance of [address]Reads a SOL balance, in SOL.
  • set [var] to [mint] balance of [address]Reads a token balance, in whole tokens.
  • set [var] to USD price of [mint]Reads the current USD price from Jupiter.
  • set [var] to [value]Stores a number, or copies another variable.
  • change [var] by [value]Adds to a variable. Use a negative number to subtract.
> ls blocks/logic<?>
  • if [left] [op] [right]Runs the blocks inside only when the comparison holds.
  • repeat [times] timesRuns the blocks inside several times in a row.

// fine print

Limits and what's behind it.

> cat limits.txt
blocks per script40
nesting of if and repeat3 levels
price check interval15 seconds
swaps and priceslite-api.jup.ag
runs in parallelnever, one at a time

Swaps and prices go through the public Jupiter API. It is free and rate limited; the address is one constant at the top of your script if you want to point it at a paid endpoint.

If a trigger fires while the stack is still running, that firing is skipped. A block that fails is printed to the terminal and the script waits for the next trigger.

Notch writes scripts. It doesn't run them, test them against your situation, or watch over them. Read the risks before you run one with real funds.