Twisp 101 gRPC Tutorial Runner

This repository contains a Go program that walks through the full Twisp 101 tutorial using the streaming AnyService gRPC API. The client reproduces every mutation/query from the GraphQL guide as a single bidirectional stream, making it easy to bootstrap a ledger, post sample transactions, and inspect the resulting balances directly from Go.

Prerequisites

• Go 1.22 or newer (the module is configured for Go 1.22 / toolchain 1.23).
• Docker for running the local Twisp environment.
• Network access to a Twisp API endpoint. You can either:
  • Run the official local container (instructions below), or
  • Point the client at a cloud-hosted Twisp cluster and supply a valid bearer token.

Start the local Twisp environment

Twisp publishes a turnkey Docker image with the API, console, and backing services. Pull and run it with:

docker pull public.ecr.aws/twisp/local:latest
docker run -p 3000:3000 -p 8080:8080 -p 8081:8081 public.ecr.aws/twisp/local:latest

The container exposes:

• http://localhost:3000 – the Twisp console (UI).
• localhost:8080 – HTTP API endpoint.
• localhost:8081 – gRPC endpoint used by this project.

You’ll see startup logs in your terminal; once the services report “ready” you can run the Go client.

Optional container settings

• Persist data across restarts: set DB_PATH and mount a volume, e.g. docker run … -e DB_PATH=/data -v twisp-data:/data ….
• Multi-tenant calls: add an X-Twisp-Account-Id header when invoking the API. If omitted, the container defaults to 000000000000, which matches the default used by this client and the console.

Refer to the local environment documentation for the full list of services and configuration options.

Running the tutorial client

Clone this repository, ensure the Twisp gRPC endpoint is reachable (the local container listens on localhost:8081), then either build or run the program:

# Build and run
go build -o grpc101 .
./grpc101

# Or run without building a binary
go run main.go

The client:

1. Opens a streaming connection to localhost:8081.
2. Replays each step of the Twisp 101 tutorial:
   • Creates the sample journal and accounts.
   • Defines ACH and internal transfer tran codes.
   • Posts the tutorial transactions (deposit, withdrawal, bank transfer).
   • Creates an account set and prints aggregate balances.
   • Fetches Ernie’s balance history and recent entries.
3. Prints progress after every step so you can follow along with the tutorial narrative.

Authentication & metadata

The code sends two metadata headers on every call:

• x-twisp-account-id: 000000000000
• Authorization: Bearer <a real token here if in cloud>

For the local container no bearer token is required, so you can leave the placeholder as-is or set it to an empty string. If you target a hosted Twisp environment replace the placeholder with a valid access token (or adjust the code to read from an environment variable).

Customising IDs or amounts

The tutorial uses fixed UUIDs so that the responses match the documented examples. Feel free to adjust them in main.go if you want to experiment with different data; each helper function references the constants declared near the top of the file.

Troubleshooting

• rpc error: code = Unavailable – confirm the Docker container is running and that you’re pointing at the correct host/port.
• Authentication failures – supply a valid bearer token when talking to a secured environment.
• State not persisting between runs – mount a volume and set DB_PATH as described above.

Further reading

• Twisp 101 tutorial
• Local environment guide
• Twisp API reference

Feel free to extend the client to cover additional tutorials, add command-line flags for different scenarios, or integrate it into automated tests once you have the local container running in CI.