feat: add first-class bankr signer backend (#6)

Author: cinnabarhorse

CHANGELOG.md

@@ -12,6 +12,15 @@
 - ABI-derived signature/input introspection for mapped help when `--abi-file` is passed.
 - Unknown command suggestion list in `UNKNOWN_COMMAND` error details.
 - CLI UX audit report: `docs/ux/cli-ux-audit-2026-02-27.md`.
+- Native `bankr` signer backend:
+  - signer spec: `bankr[:address|apiKeyEnv|apiUrl]`
+  - default auth env var: `BANKR_API_KEY`
+  - default API URL: `https://api.bankr.bot`
+  - address auto-resolution via `GET /agent/me` when address is not pinned
+  - transaction submit via `POST /agent/submit`
+- Bootstrap overrides now support `bankr`:
+  - `--signer-address` to pin wallet address
+  - `--signer-auth-env-var` to customize Bankr API key env var
 
 ### Changed
 

README.md

@@ -175,12 +175,26 @@ npm run ag -- auction active --first 5 --raw --json
 - `keychain:ACCOUNT_ID` (encrypted local key store; requires `AGCLI_KEYCHAIN_PASSPHRASE`)
 - `remote:URL|ADDRESS|AUTH_ENV` (HTTP signer service)
 - `ledger:DERIVATION_PATH|ADDRESS|BRIDGE_ENV` (external bridge command signer)
+- `bankr[:ADDRESS|API_KEY_ENV|API_URL]` (Bankr-native signer via `/agent/me` + `/agent/submit`; defaults: `BANKR_API_KEY`, `https://api.bankr.bot`)
 
 Remote signer contract:
 
 - `GET /address` -> `{ "address": "0x..." }` (optional if address configured)
 - `POST /sign-transaction` -> `{ "rawTransaction": "0x..." }` or `{ "txHash": "0x..." }`
 
+Bankr signer contract:
+
+- `GET /agent/me` -> resolves wallet address when signer address is not pinned
+- `POST /agent/submit` -> submits transaction and returns transaction hash
+- auth header: `x-api-key: <BANKR_API_KEY>`
+
+Bankr bootstrap example:
+
+```bash
+BANKR_API_KEY=... \
+npm run ag -- bootstrap --mode agent --profile bankr --chain base --signer bankr --json
+```
+
 Ledger bridge contract:
 
 - Set `AGCLI_LEDGER_BRIDGE_CMD` (or custom env var in signer config) to a command that reads tx payload JSON from stdin and outputs JSON containing either `rawTransaction` or `txHash`.

src/commands/bootstrap.ts

@@ -39,6 +39,17 @@ function buildSignerConfig(ctx: CommandContext, signerInput: string): ProfileCon
         };
     }
 
+    if (signer.type === "bankr") {
+        const address = getFlagString(ctx.args.flags, "signer-address");
+        const apiKeyEnvVar = getFlagString(ctx.args.flags, "signer-auth-env-var");
+
+        return {
+            ...signer,
+            ...(address ? { address: address as `0x${string}` } : {}),
+            ...(apiKeyEnvVar ? { apiKeyEnvVar } : {}),
+        };
+    }
+
     if (signer.type === "ledger") {
         const address = getFlagString(ctx.args.flags, "signer-address");
         const bridgeCommandEnvVar = getFlagString(ctx.args.flags, "signer-bridge-env-var");

src/output.ts

@@ -88,6 +88,7 @@ Examples:
   ag bootstrap --profile prod --chain base --signer readonly --json
   ag tx send --profile prod --to 0xabc... --value-wei 0 --dry-run --json
   ag onchain send --profile prod --abi-file ./abi.json --address 0xabc... --function approve --args-json '["0xdef...", "1"]' --dry-run --json
+  BANKR_API_KEY=... ag bootstrap --profile bankr --chain base --signer bankr --json
   ag baazaar buy-now --help
   ag help tx send
 `;
@@ -107,6 +108,7 @@ Signer formats:
   keychain:ACCOUNT_ID
   ledger[:DERIVATION_PATH|ADDRESS|BRIDGE_ENV_VAR]
   remote:URL|ADDRESS|AUTH_ENV_VAR
+  bankr[:ADDRESS|API_KEY_ENV|API_URL]
 `,
     profile: `
 Usage:

src/schemas.ts

@@ -21,6 +21,12 @@ export const signerSchema = z.discriminatedUnion("type", [
         address: addressSchema.optional(),
         authEnvVar: z.string().regex(/^[A-Z_][A-Z0-9_]*$/).optional(),
     }),
+    z.object({
+        type: z.literal("bankr"),
+        address: addressSchema.optional(),
+        apiKeyEnvVar: z.string().regex(/^[A-Z_][A-Z0-9_]*$/).optional(),
+        apiUrl: z.string().url().optional(),
+    }),
 ]);
 
 export const policySchema = z.object({

src/signer-runtime.test.ts

@@ -20,6 +20,8 @@ const tempFiles: string[] = [];
 afterEach(() => {
     delete process.env.AGCLI_REMOTE_TOKEN;
     delete process.env.AGCLI_LEDGER_BRIDGE_CMD;
+    delete process.env.BANKR_API_KEY;
+    delete process.env.BANKR_TEST_KEY;
 
     for (const file of tempFiles.splice(0)) {
         fs.rmSync(file, { force: true });
@@ -134,4 +136,79 @@ describe("signer runtime", () => {
 
         expect(hash).toBe("0x" + "c".repeat(64));
     });
+
+    it("supports bankr signer with wallet auto-discovery", async () => {
+        process.env.BANKR_API_KEY = "bankr-token";
+
+        const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
+            if (url.endsWith("/agent/me")) {
+                expect((init?.headers as Record<string, string>)["x-api-key"]).toBe("bankr-token");
+                return {
+                    ok: true,
+                    text: async () => JSON.stringify({ walletAddress: "0x0000000000000000000000000000000000000001" }),
+                };
+            }
+
+            expect(url.endsWith("/agent/submit")).toBe(true);
+            expect((init?.headers as Record<string, string>)["x-api-key"]).toBe("bankr-token");
+            const body = JSON.parse(String(init?.body));
+            expect(body.waitForConfirmation).toBe(false);
+            expect(body.transaction.to).toBe("0x0000000000000000000000000000000000000001");
+            return {
+                ok: true,
+                text: async () => JSON.stringify({ transactionHash: "0x" + "e".repeat(64) }),
+            };
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const signer = parseSigner("bankr");
+        const runtime = await resolveSignerRuntime(signer, fakePublicClient(), "https://mainnet.base.org", base);
+
+        expect(runtime.summary.signerType).toBe("bankr");
+        expect(runtime.summary.address).toBe("0x0000000000000000000000000000000000000001");
+        expect(runtime.summary.canSign).toBe(true);
+
+        const hash = await runtime.sendTransaction!({
+            chain: base,
+            to: "0x0000000000000000000000000000000000000001",
+            data: "0x",
+            value: 0n,
+            gas: 21000n,
+            nonce: 1,
+        });
+
+        expect(hash).toBe("0x" + "e".repeat(64));
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it("supports bankr signer with explicit address and custom api key env var", async () => {
+        process.env.BANKR_TEST_KEY = "bankr-token";
+
+        const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
+            expect(url).toBe("https://api.bankr.bot/agent/submit");
+            expect((init?.headers as Record<string, string>)["x-api-key"]).toBe("bankr-token");
+            return {
+                ok: true,
+                text: async () => JSON.stringify({ txHash: "0x" + "f".repeat(64) }),
+            };
+        });
+        vi.stubGlobal("fetch", fetchMock);
+
+        const signer = parseSigner(
+            "bankr:0x0000000000000000000000000000000000000001|BANKR_TEST_KEY|https://api.bankr.bot",
+        );
+        const runtime = await resolveSignerRuntime(signer, fakePublicClient(), "https://mainnet.base.org", base);
+
+        const hash = await runtime.sendTransaction!({
+            chain: base,
+            to: "0x0000000000000000000000000000000000000001",
+            data: "0x",
+            value: 0n,
+            gas: 21000n,
+            nonce: 1,
+        });
+
+        expect(hash).toBe("0x" + "f".repeat(64));
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
 });

src/signer.test.ts

@@ -57,6 +57,23 @@ describe("agcli signer parser", () => {
         });
     });
 
+    it("parses bankr signer defaults", () => {
+        expect(parseSigner("bankr")).toEqual({
+            type: "bankr",
+        });
+    });
+
+    it("parses bankr signer with address, api env, and api url", () => {
+        expect(
+            parseSigner("bankr:0x0000000000000000000000000000000000000001|BANKR_KEY|https://api.bankr.bot"),
+        ).toEqual({
+            type: "bankr",
+            address: "0x0000000000000000000000000000000000000001",
+            apiKeyEnvVar: "BANKR_KEY",
+            apiUrl: "https://api.bankr.bot",
+        });
+    });
+
     it("throws for malformed env name", () => {
         expect(() => parseSigner("env:agcli_key")).toThrowError();
     });