Local API

curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8081/v1/balance

# skip the 15-second cache and read the chain now
curl -s -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:8081/v1/balance?fresh=1"

$r = Invoke-RestMethod -Headers $h "http://127.0.0.1:8081/v1/balance?fresh=1"
"Private balance: $($r.result.shielded) USDG"
"Agent wallet:    $($r.result.wallet.usdg) USDG, $($r.result.wallet.sol) SOL"
$r.result.allowances | Format-Table id, remaining, holder, reclaimable

r = call("GET", "/balance", params={"fresh": "1"})["result"]
print("private:", r["shielded"], "USDG")
print("wallet: ", r["wallet"]["usdg"], "USDG,", r["wallet"]["sol"], "SOL")
for a in r["allowances"]:
    print("budget", a["id"], a["remaining"], "left,", a["holder"])

const r = (await call('GET', '/balance?fresh=1')).result;
console.log(`private: ${r.shielded} USDG, wallet: ${r.wallet.usdg} USDG and ${r.wallet.sol} SOL`);
for (const a of r.allowances) console.log('budget', a.id, a.remaining, 'left,', a.holder);

# 1 · the plan: nothing is sent
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"usdg":"5"}' http://127.0.0.1:8081/v1/deposit

# 2 · send it: "confirm": true and an Idempotency-Key (keep KEY if you need to retry)
KEY=dep-$(date +%s)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" -d '{"usdg":"5","confirm":true}' http://127.0.0.1:8081/v1/deposit

# 1 · the plan: nothing is sent
$body = @{ usdg = "5" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body $body http://127.0.0.1:8081/v1/deposit

# 2 · send it (keep $key if you need to retry)
$key = [guid]::NewGuid().ToString()
$body = @{ usdg = "5"; confirm = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post -Headers ($h + @{ "Idempotency-Key" = $key }) -ContentType application/json -Body $body http://127.0.0.1:8081/v1/deposit

plan = call("POST", "/deposit", {"usdg": "5"})
print(plan["status"], plan["result"]["warnings"])        # "plan": nothing is sent

sent = call("POST", "/deposit", {"usdg": "5", "confirm": True}, key=str(uuid.uuid4()))
print(sent["result"]["signature"], sent["result"]["shieldedUsdg"])

const plan = await call('POST', '/deposit', { usdg: '5' });   // nothing is sent
console.log(plan.status, plan.result.warnings);

const sent = await call('POST', '/deposit', { usdg: '5', confirm: true }, randomUUID());
console.log(sent.result.signature, sent.result.shieldedUsdg);

# 1 · the plan: fee, what arrives, what is public (nothing is sent)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"usdg":"2","to":"<fresh wallet>"}' http://127.0.0.1:8081/v1/withdraw

# 2 · send it
KEY=wd-$(date +%s)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" -d '{"usdg":"2","to":"<fresh wallet>","confirm":true}' http://127.0.0.1:8081/v1/withdraw

$to = "<fresh wallet>"
# 1 · the plan (nothing is sent)
$body = @{ usdg = "2"; to = $to } | ConvertTo-Json
(Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body $body http://127.0.0.1:8081/v1/withdraw).result

# 2 · send it
$key = [guid]::NewGuid().ToString()
$body = @{ usdg = "2"; to = $to; confirm = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post -Headers ($h + @{ "Idempotency-Key" = $key }) -ContentType application/json -Body $body http://127.0.0.1:8081/v1/withdraw

to = "<fresh wallet>"                     # a wallet that never touched the agent
print(call("GET", "/fees/withdraw", params={"usdg": "2"})["result"])

plan = call("POST", "/withdraw", {"usdg": "2", "to": to})
print(plan["result"]["fee"], plan["result"]["payout"], plan["result"]["warnings"])   # nothing is sent

sent = call("POST", "/withdraw", {"usdg": "2", "to": to, "confirm": True}, key=str(uuid.uuid4()))
print(sent["result"]["signature"], sent["result"]["receivedUsdg"])

const to = '<fresh wallet>';                       // a wallet that never touched the agent
const plan = await call('POST', '/withdraw', { usdg: '2', to });   // nothing is sent
console.log(plan.result.fee, plan.result.payout, plan.result.warnings);

const sent = await call('POST', '/withdraw', { usdg: '2', to, confirm: true }, randomUUID());
console.log(sent.result.signature, sent.result.receivedUsdg);

# 1 · the plan: pay 1 USDG privately to another H081 account (nothing is sent)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"usdg":"1","toAddressCode":"h081-address:…"}' http://127.0.0.1:8081/v1/pay

# 2 · send it
KEY=pay-$(date +%s)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" -d '{"usdg":"1","toAddressCode":"h081-address:…","confirm":true}' \
  http://127.0.0.1:8081/v1/pay

$code = "h081-address:…"
# 1 · the plan (nothing is sent)
$body = @{ usdg = "1"; toAddressCode = $code } | ConvertTo-Json
(Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body $body http://127.0.0.1:8081/v1/pay).result

# 2 · send it
$key = [guid]::NewGuid().ToString()
$body = @{ usdg = "1"; toAddressCode = $code; confirm = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post -Headers ($h + @{ "Idempotency-Key" = $key }) -ContentType application/json -Body $body http://127.0.0.1:8081/v1/pay

# private: to an h081-address: code
body = {"usdg": "1", "toAddressCode": "h081-address:…"}
print(call("POST", "/pay", body)["result"])                        # the plan: nothing is sent
sent = call("POST", "/pay", {**body, "confirm": True}, key=str(uuid.uuid4()))
print(sent["result"]["signature"], sent["result"].get("remaining"))

# public payout: to a fresh wallet, from one budget only (the plan).
# The budget id is the long number GET /v1/balance shows.
body = {"usdg": "1", "to": "<fresh wallet>", "allowanceId": "<budget id>"}
print(call("POST", "/pay", body)["result"])

const body = { usdg: '1', toAddressCode: 'h081-address:…' };
console.log((await call('POST', '/pay', body)).result);              // the plan: nothing is sent

const sent = await call('POST', '/pay', { ...body, confirm: true }, randomUUID());
console.log(sent.result.signature);

# 1 · the plan (nothing is sent)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"usdg":"1.5","toAddressCode":"h081-address:…"}' http://127.0.0.1:8081/v1/transfer

# 2 · send it
KEY=tr-$(date +%s)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" -d '{"usdg":"1.5","toAddressCode":"h081-address:…","confirm":true}' \
  http://127.0.0.1:8081/v1/transfer

$code = "h081-address:…"
# 1 · the plan (nothing is sent)
$body = @{ usdg = "1.5"; toAddressCode = $code } | ConvertTo-Json
(Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body $body http://127.0.0.1:8081/v1/transfer).result

# 2 · send it
$key = [guid]::NewGuid().ToString()
$body = @{ usdg = "1.5"; toAddressCode = $code; confirm = $true } | ConvertTo-Json
Invoke-RestMethod -Method Post -Headers ($h + @{ "Idempotency-Key" = $key }) -ContentType application/json -Body $body http://127.0.0.1:8081/v1/transfer

body = {"usdg": "1.5", "toAddressCode": "h081-address:…"}
print(call("POST", "/transfer", body)["result"]["warnings"])       # the plan: nothing is sent

sent = call("POST", "/transfer", {**body, "confirm": True}, key=str(uuid.uuid4()))
print(sent["result"]["signature"], sent["result"]["shieldedUsdg"])

const body = { usdg: '1.5', toAddressCode: 'h081-address:…' };
console.log((await call('POST', '/transfer', body)).result.warnings);   // nothing is sent

const sent = await call('POST', '/transfer', { ...body, confirm: true }, randomUUID());
console.log(sent.result.signature, sent.result.shieldedUsdg);

# 1 · the plan: 20 USDG budget for sub-account 0, at most 5 a day and 2 per payment, for 30 days
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"budget":"20","dailyCap":"5","maxPerTx":"2","days":30,"agentIndex":0}' \
  http://127.0.0.1:8081/v1/allowances

# 2 · send it
KEY=allow-$(date +%s)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"budget":"20","dailyCap":"5","maxPerTx":"2","days":30,"agentIndex":0,"confirm":true}' \
  http://127.0.0.1:8081/v1/allowances

# 1 · the plan (nothing is sent)
$rules = @{ budget = "20"; dailyCap = "5"; maxPerTx = "2"; days = 30; agentIndex = 0 }
(Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body ($rules | ConvertTo-Json) http://127.0.0.1:8081/v1/allowances).result

# 2 · send it
$key = [guid]::NewGuid().ToString()
$rules.confirm = $true
Invoke-RestMethod -Method Post -Headers ($h + @{ "Idempotency-Key" = $key }) -ContentType application/json -Body ($rules | ConvertTo-Json) http://127.0.0.1:8081/v1/allowances

rules = {"budget": "20", "dailyCap": "5", "maxPerTx": "2", "days": 30, "agentIndex": 0}
print(call("POST", "/allowances", rules)["result"])                # the plan: nothing is sent

sent = call("POST", "/allowances", {**rules, "confirm": True}, key=str(uuid.uuid4()))
print("budget id:", sent["result"]["allowanceId"])

const rules = { budget: '20', dailyCap: '5', maxPerTx: '2', days: 30, agentIndex: 0 };
console.log((await call('POST', '/allowances', rules)).result);   // the plan: nothing is sent

const sent = await call('POST', '/allowances', { ...rules, confirm: true }, randomUUID());
console.log('budget id:', sent.result.allowanceId);

# the budget's current id, from GET /v1/balance (a long number)
ID="<budget id>"

# 1 · the plan (nothing is sent)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{}' http://127.0.0.1:8081/v1/allowances/$ID/reclaim

# 2 · take it back
KEY=reclaim-$(date +%s)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" -d '{"confirm":true}' http://127.0.0.1:8081/v1/allowances/$ID/reclaim

$id = "<budget id>"     # its current id, from GET /v1/balance
# 1 · the plan (nothing is sent)
(Invoke-RestMethod -Method Post -Headers $h -ContentType application/json -Body '{}' "http://127.0.0.1:8081/v1/allowances/$id/reclaim").result

# 2 · take it back
$key = [guid]::NewGuid().ToString()
Invoke-RestMethod -Method Post -Headers ($h + @{ "Idempotency-Key" = $key }) -ContentType application/json -Body '{"confirm":true}' "http://127.0.0.1:8081/v1/allowances/$id/reclaim"

bid = "<budget id>"                          # its current id, from GET /v1/balance
print(call("POST", f"/allowances/{bid}/reclaim", {})["result"])   # the plan: nothing is sent

sent = call("POST", f"/allowances/{bid}/reclaim", {"confirm": True}, key=str(uuid.uuid4()))
print(sent["result"]["reclaimedUsdg"], "USDG back")

const id = '<budget id>';                       // its current id, from GET /v1/balance
console.log((await call('POST', `/allowances/${id}/reclaim`, {})).result);   // nothing is sent

const sent = await call('POST', `/allowances/${id}/reclaim`, { confirm: true }, randomUUID());
console.log(sent.result.reclaimedUsdg, 'USDG back');

curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8081/v1/events

# pip install requests
import json, pathlib, requests

TOKEN = (pathlib.Path.home() / ".h081" / "api-token").read_text().strip()
URL = "http://127.0.0.1:8081/v1/events"
last_id = None                       # sent back as Last-Event-ID to resume after a drop

while True:
    headers = {"Authorization": "Bearer " + TOKEN}
    if last_id:
        headers["Last-Event-ID"] = last_id
    try:
        with requests.get(URL, headers=headers, stream=True, timeout=(5, 60)) as r:
            r.raise_for_status()
            event, data = None, None
            for line in r.iter_lines(decode_unicode=True):
                if line.startswith("id: "):
                    last_id = line[4:]
                elif line.startswith("event: "):
                    event = line[7:]
                elif line.startswith("data: "):
                    data = json.loads(line[6:])
                elif line == "" and event:            # a blank line ends one event
                    print(event, data)
                    if event == "balance.changed":
                        print("private balance is now", data["shielded"], "USDG")
                    event, data = None, None
    except requests.RequestException as e:
        print("reconnecting:", e)

// Node.js 20+. A browser EventSource cannot send the Authorization header, so this reads the stream with fetch.
import { readFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { join } from 'node:path';

const token = readFileSync(join(homedir(), '.h081', 'api-token'), 'utf8').trim();
const res = await fetch('http://127.0.0.1:8081/v1/events', { headers: { Authorization: `Bearer ${token}` } });
if (!res.ok || !res.body) throw new Error(`events: HTTP ${res.status}`);

const decoder = new TextDecoder();
let buf = '';
for await (const chunk of res.body) {
  buf += decoder.decode(chunk, { stream: true });
  let end;
  while ((end = buf.indexOf('\n\n')) >= 0) {          // a blank line ends one event
    const block = buf.slice(0, end);
    buf = buf.slice(end + 2);
    const ev: Record<string, string> = {};
    for (const line of block.split('\n')) {
      const i = line.indexOf(': ');
      if (i > 0) ev[line.slice(0, i)] = line.slice(i + 2);   // skips ": ping" comments
    }
    if (ev.event) console.log(ev.id, ev.event, JSON.parse(ev.data));
  }
}