Set up oathline

Agent wallet

1. Owner: sign the rules

   Open app.oathline.io/setup, sign in with Telegram and choose My agent’s own wallet. Enter the agent’s wallet address and the invite code, write the rules, read what oathline understood, then sign with your browser wallet. Signing is free and moves no money. Link Telegram at the end.

   Writing good rules

   Write them the way you would brief a new employee: the tokens it may use, a limit per trade and per day, where money may go, and the contracts it may call.

   “Trade only ETH, WETH and USDC. At most 0.5 ETH per trade and 2 ETH per day. Money may only be sent to my saved address 0x….”

   If your agent calls contracts of its own, name them with their full function signatures: “my agent may call its own contract 0x… (only addWorker(address))”. A listed call is then allowed when the simulation shows nothing at stake. This needs SDK 0.1.1 or newer. To change the rules later, sign new ones; the newest set counts.

   Prefer a script?

   // owner.ts: run on YOUR computer, never on the agent's server
   import { privateKeyToAccount } from 'viem/accounts'
   import { compileMandate, setMandate, linkTelegram } from '@oathline/sdk'
   
   const API = 'https://api.oathline.io'
   const setup = { chainId: 8453, invite: 'oi_…' }
   const owner = privateKeyToAccount(process.env.OWNER_KEY as `0x${string}`)
   const AGENT = '0xYourAgentWalletAddress'
   
   const rules = 'Trade only ETH, WETH and USDC. At most 0.5 ETH per trade and 2 ETH per day. ' +
                 'Money may only be sent to my saved address 0x….'
   const { compiled, shownToOwner } = await compileMandate(API, rules)   // about 20 seconds
   console.log(shownToOwner)                                              // read it: this is what you sign
   if (compiled.unresolved?.length) console.log('Not turned into a rule:', compiled.unresolved)
   await setMandate(API, owner, AGENT, rules, compiled, setup)
   
   const { url } = await linkTelegram(API, owner, AGENT, { chainId: 8453 })
   console.log('Open in Telegram and press Start:', url)                  // works once, for 15 minutes

2. Builder: install and register the agent once

   npm install @oathline/sdk viem

   import { privateKeyToAccount } from 'viem/accounts'
   import { registerWallet } from '@oathline/sdk'
   
   const agentAccount = privateKeyToAccount(process.env.AGENT_KEY as `0x${string}`)
   const API = 'https://api.oathline.io'
   const { apiKey } = await registerWallet(API, agentAccount, '0xOwnerAddress',
     { chainId: 8453, invite: 'oi_…' })
   // shown once: store it as a secret, e.g. OATHLINE_API_KEY

   Run this once, not on every deploy. The owner a wallet names first is permanent, so check the address.

   AgentKit, or no raw key

   // `provider`: your AgentKit wallet provider, not wrapped yet
   const { apiKey } = await registerWallet('https://api.oathline.io', {
     address: provider.getAddress() as `0x${string}`,
     signTypedData: (args) => provider.signTypedData(args),
   }, '0xOwnerAddress', { chainId: 8453, invite: 'oi_…' })

3. Builder: wrap the wallet, in shadow mode

   import { createWalletClient, http } from 'viem'
   import { base } from 'viem/chains'
   import { Oathline } from '@oathline/sdk'
   
   const oathline = new Oathline({
     apiUrl: 'https://api.oathline.io',
     apiKey: process.env.OATHLINE_API_KEY!,
     chainId: 8453,
     mode: 'shadow',      // watches only; leave it out and you get 'enforce'
     timeoutMs: 8000,
     onDecision: (r, tx, d) => console.log(d, r.verdict, r.reason),
   })
   
   // create the client WITH the agent's account: the check is for that address
   const walletClient = createWalletClient({ account: agentAccount, chain: base, transport: http() })
   const wallet = oathline.guard(walletClient)   // the agent now uses `wallet`, never `walletClient`

   Keep the original client private: anything that signs through it, or through a library you give a raw key to (many x402 payment clients do), skips oathline. On the wrapped wallet, sendTransaction, writeContract and signTransaction are checked; sendCalls, signAuthorization and sendRawTransaction pass straight through, so do not give those to the agent.

   AgentKit

   const walletProvider = oathline.guardWalletProvider(provider)
   const agentkit = await AgentKit.from({ walletProvider, actionProviders: [/* yours */] })
   // give the agent only `agentkit`; keep `provider` private

4. Check that it works

   const r = await oathline.check(agentAccount.address, { to: '0xYourSavedAddress', data: '0x', value: 0n })
   console.log(r.verdict, r.reason)   // any verdict is fine: it came back signed for this exact transaction

   Then let the agent run as usual. You get a Telegram notice whenever oathline would have asked or blocked, and every decision with its reason is on the dashboard.

5. After about a week: enforce

   Shadow and enforce, in one minute. Shadow mode checks everything and blocks nothing. In enforce mode a block stops the signature, an ask waits for your Approve or Reject on Telegram, and if oathline cannot be reached the agent refuses to sign. Today the builder switches in the code, as below; a switch the owner signs on the dashboard is planned.

   const oathline = new Oathline({
     /* same as above, and: */
     mode: 'enforce',
     failClosed: true,
     timeoutMs: 30000,
     signatures: 'refuse',   // permits, x402, signed logins: 'refuse', 'ask' + onAsk, or 'allow'
   })

   Verdict	What happens
   allow	Signed
   ask	Approve or Reject goes to your Telegram, for up to 10 minutes. No answer means refused. Without a linked Telegram it is refused at once, unless you set an onAsk hook
   block	Refused. A block can never be approved

   Catch OathlineBlocked, OathlineNeedsApproval and OathlineUnavailable in the agent and tell it why. Raise your framework’s tool timeout above 10 minutes so an ask is not cut off.

In enforce mode a tricked agent’s transaction is refused when the check catches it. A hacked agent server is different: it holds the key and can sign without the SDK. For that, put the money behind a Safe cosigner.

Safe cosigner

Base Sepolia test network, test money only. On Base mainnet it opens later, first for a few design partners.

The Safe has three keys and needs two: the agent, oathline (it signs only what passes) and you, kept offline. The agent alone moves nothing. You and the agent together can always act without oathline, including removing it.

You need test ETH from a faucet for the owner (to create the Safe), for the agent (gas) and in the Safe itself. The test server is open: no invite code.

1. Owner: create a fresh Safe and register your half

   oathline accepts only a plainly created Safe 1.4.1: the standard factory, exactly these three owners, no modules, no guard. Safes made in the Safe web app are not accepted yet; adding oathline to a Safe you already have is coming.

   import { createPublicClient, createWalletClient, http,
     encodeFunctionData, decodeEventLog, getAddress } from 'viem'
   import { baseSepolia } from 'viem/chains'
   import { privateKeyToAccount } from 'viem/accounts'
   import { safeAbi, safeProxyFactoryAbi, registerSafePartial } from '@oathline/sdk'
   
   const API = 'https://sepolia.oathline.io'
   const AGENT = '0xYourAgentWalletAddress'
   const owner = privateKeyToAccount(process.env.OWNER_KEY as `0x${string}`)
   const ZERO = '0x0000000000000000000000000000000000000000'
   const pub = createPublicClient({ chain: baseSepolia, transport: http() })
   const ownerWallet = createWalletClient({ account: owner, chain: baseSepolia, transport: http() })
   
   const c = await (await fetch(`${API}/safe/contracts`)).json()   // { singleton, factory, cosigner, chainId }
   if (c.chainId !== 84532) throw new Error('wrong server')
   // check c.cosigner against Reference below, and singleton and factory
   // against Safe's published deployments
   
   const owners = [getAddress(AGENT), getAddress(c.cosigner), owner.address]
   const saltNonce = BigInt(Date.now())
   const initializer = encodeFunctionData({ abi: safeAbi, functionName: 'setup',
     args: [owners, 2n, ZERO, '0x', ZERO, ZERO, 0n, ZERO] })
   const hash = await ownerWallet.writeContract({ address: c.factory, abi: safeProxyFactoryAbi,
     functionName: 'createProxyWithNonce', args: [c.singleton, initializer, saltNonce] })
   const receipt = await pub.waitForTransactionReceipt({ hash })
   let SAFE: `0x${string}` | undefined
   for (const l of receipt.logs) {
     try {
       const ev = decodeEventLog({ abi: safeProxyFactoryAbi, data: l.data, topics: l.topics })
       if (ev.eventName === 'ProxyCreation') SAFE = ev.args.proxy
     } catch {}
   }
   
   await registerSafePartial(API, SAFE!, [owner], owner.address,
     { owners, threshold: 2, saltNonce })

2. Owner: sign the rules for the Safe

   import { compileMandate, setMandate } from '@oathline/sdk'
   
   const rules = 'Pay only my saved address 0x…. At most 0.05 ETH per payment. Never change owners.'
   const { compiled, shownToOwner } = await compileMandate(API, rules)
   console.log(shownToOwner)                   // read it: this is what you sign
   await setMandate(API, owner, SAFE!, rules, compiled, { chainId: 84532 })

   No invite code on the test server, and no Telegram: an ask there is refused.

3. Agent: complete the registration and send through the Safe

   import { Oathline, registerSafe, sendViaSafe } from '@oathline/sdk'
   
   const API = 'https://sepolia.oathline.io'
   const SAFE = '0xTheSafe', OWNER = '0xTheOwner'
   const { apiKey } = await registerSafe(API, SAFE, [agentAccount], OWNER)   // once
   
   const oathline = new Oathline({ apiUrl: API, apiKey, chainId: 84532 })
   // walletClient: the agent's own client; it signs the Safe transaction and pays the gas
   const txHash = await sendViaSafe(oathline, { publicClient, walletClient }, SAFE,
     { to, data, value })

   There is no shadow mode here: without oathline’s signature the Safe does not move.

Limits today: single calls only (approve, then swap, is two transactions), no delegatecall, no batches. A cosigned transaction stays valid until the next one replaces it. Spending is counted when a transaction is allowed, not when it runs. Exit: you and the agent sign removeOwner together, without oathline.

Watch a Safe

Base mainnet. Warns, cannot stop anything. Nothing about your Safe changes and oathline holds no key.

Every proposal waiting for signatures (from the Safe app or anything using Safe’s Transaction Service) is checked within about 15 seconds. oathline rehearses the exact execution on a copy of Base, compares the Safe’s owners, threshold, modules and guard before and after, and judges the result against your rules. You get “Do not sign this”, “Look before you sign” or “Looks fine” on Telegram and the dashboard.

One owner of the Safe runs this once

One signature from one of the Safe’s owners is enough. (The dashboard’s “Watch a Safe” button is not available on the hosted dashboard yet.)

import { watchSafe, compileMandate, setMandate, linkTelegram, watchVerdicts } from '@oathline/sdk'

const API = 'https://api.oathline.io'
const SAFE = '0xYourSafeAddress'     // safeOwner: a viem account of one of the Safe's owners
const { apiKey } = await watchSafe(API, SAFE, safeOwner, safeOwner.address, { invite: 'oi_…' })

const rules = 'Payments only to our three saved vendor addresses 0x…, 0x…, 0x…. ' +
              'At most 50,000 USDC per payment. Never change owners or threshold.'
const { compiled, shownToOwner } = await compileMandate(API, rules)
console.log(shownToOwner)
await setMandate(API, safeOwner, SAFE, rules, compiled)
const { url } = await linkTelegram(API, safeOwner, SAFE)   // open in Telegram, press Start
console.log(url)

console.log(await watchVerdicts(API, apiKey))               // later: what oathline said about recent proposals

To make oathline’s “no” count, move the money to a Safe cosigner (test network today).