feat: add first-class bankr signer backend

Author: cinnabarhorse

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- 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
+
 ## 0.2.1 - 2026-02-27
 
 ### Added

README.md

@@ -147,12 +147,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

@@ -112,9 +112,9 @@ Bootstrap flags:
   --profile NAME                     Profile to create or update (required)
   --chain base|base-sepolia|<id>     Chain key or numeric chain id (default: base)
   --rpc-url URL                      RPC endpoint (optional when chain preset exists)
-  --signer readonly|env:VAR|keychain:<id>|ledger[:path|address|bridgeEnv]|remote:<url|address|authEnv>
-  --signer-address 0x...             Optional override for remote/ledger signer address
-  --signer-auth-env-var ENV_VAR      Optional remote signer bearer token env var
+  --signer readonly|env:VAR|keychain:<id>|ledger[:path|address|bridgeEnv]|remote:<url|address|authEnv>|bankr[:address|apiKeyEnv|apiUrl]
+  --signer-address 0x...             Optional override for remote/ledger/bankr signer address
+  --signer-auth-env-var ENV_VAR      Optional remote bearer token or bankr API key env var
   --signer-bridge-env-var ENV_VAR    Optional ledger bridge command env var name
   --policy NAME                      Policy label (default: default)
   --skip-signer-check                Persist signer config without backend validation
@@ -124,6 +124,7 @@ Examples:
   AGCLI_KEYCHAIN_PASSPHRASE=... AGCLI_PRIVATE_KEY=0x... ag signer keychain import --account-id bot --private-key-env AGCLI_PRIVATE_KEY --json
   ag tx send --profile prod --to 0xabc... --value-wei 1000000000000000 --wait --json
   ag tx send --profile prod --to 0xabc... --value-wei 0 --dry-run --json
+  BANKR_API_KEY=... ag bootstrap --mode agent --profile bankr --chain base --signer bankr --json
   ag subgraph check --source core-base --json
   ag baazaar listing active --kind erc721 --first 20 --json
   ag auction active --first 20 --json

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();
     });