btx-agent-gateway

BTX Agent Gateway is an experimental developer toolkit for testing MatMul-based service challenges as an access-control primitive for AI agents and API infrastructure.

This repository is intentionally narrow. It does not promote a token, does not make production-readiness claims, and does not provide investment advice.

Release notes are in CHANGELOG.md. Planned public work is in ROADMAP.md.

What Works Today

• BtxRpcClient provides a configurable TypeScript JSON-RPC client for a BTX node or compatible adapter.
• MockBtxRpcClient provides an in-memory local mock for development without a live BTX node.
• createBtxChallengeRouter exposes the standard challenge routes for Express.
• createBtxChallengeMiddleware protects Express routes with proof redemption.
• The Express example runs the standard routes in mock mode by default.
• The FastAPI example exposes the same route names for local integration testing.
• examples/openapi.yaml documents the public route shape in a machine-readable form.
• The repository includes integration notes, risk notes, benchmark planning, and a public roadmap.

What Is Not Implemented

• Shared replay protection across multiple gateway processes or instances.
• Production authentication, authorization, or rate limiting around protected endpoints.
• Live BTX compatibility guarantees beyond the documented assumptions.
• Request binding beyond the current challenge envelope and proof payload fields.
• Failure-policy controls for fail-open, fail-closed, or degraded behavior.
• Any investment, token, or mining claims.
• Any claim that BTX Service Challenges are ready for critical infrastructure.

Planned follow-up work is tracked in ROADMAP.md.

Standard Routes

Both examples use the same public route shape:

GET  /health
GET  /btx/health
POST /btx/challenge
POST /btx/challenge/redeem
GET  /protected/demo

/protected/demo expects an x-btx-proof header containing base64url-encoded JSON proof, or raw JSON in the Express example.

See examples/openapi.yaml for the machine-readable route summary.

Quick Start

The Express example runs in mock mode by default. No BTX node is required.

pnpm install
pnpm dev:express

In a second terminal, run an end-to-end local request:

node --input-type=module <<'EOF'
const baseUrl = "http://localhost:3000";

const challenge = await fetch(`${baseUrl}/btx/challenge`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    subject: "agent:demo",
    action: "protected-demo"
  })
}).then((response) => response.json());

const modulus = challenge.modulus;
const result = challenge.matrixA.map((row, rowIndex) =>
  challenge.matrixB[0].map((_, columnIndex) =>
    row.reduce((total, value, sharedIndex) =>
      (total + value * challenge.matrixB[sharedIndex][columnIndex]) % modulus,
    0)
  )
);
const proof = {
  challengeId: challenge.challengeId,
  domain: challenge.domain,
  result,
  solver: "local-demo"
};
const proofHeader = Buffer.from(JSON.stringify(proof), "utf8").toString("base64url");

const protectedResponse = await fetch(`${baseUrl}/protected/demo`, {
  headers: { "x-btx-proof": proofHeader }
}).then((response) => response.json());

console.log(JSON.stringify({ challenge, protectedResponse }, null, 2));
EOF

Expected result: the protected response contains "ok": true.

Docker Compose

Start both examples in mock mode from a clean clone:

docker compose up

Express listens on http://localhost:3000 and FastAPI listens on http://localhost:8000.

Repository Layout

.
├── CHANGELOG.md
├── ROADMAP.md
├── docs/
│   ├── architecture.md
│   ├── benchmark-plan.md
│   ├── btx-rpc-assumptions.md
│   ├── integration-guide.md
│   └── risk-notes.md
├── examples/
│   ├── openapi.yaml
│   ├── express-api-gateway/
│   └── fastapi-gateway/
├── packages/
│   ├── btx-client-ts/
│   └── challenge-middleware/
├── scripts/
│   └── benchmark-mock.ts
└── tests/

Configuration

Copy .env.example to .env for local work if you need to change defaults.

Important variables:

• BTX_USE_MOCK: defaults to mock mode unless set to false.
• BTX_RPC_URL: JSON-RPC URL used when BTX_USE_MOCK=false.
• BTX_RPC_USER and BTX_RPC_PASSWORD: optional JSON-RPC basic auth credentials.
• BTX_CHALLENGE_DOMAIN: server-controlled domain binding for challenges.
• BTX_CHALLENGE_TTL_SECONDS: server-controlled challenge TTL.
• BTX_MOCK_MATRIX_SIZE and BTX_MOCK_MODULUS: local mock challenge parameters.

See BTX RPC assumptions before connecting a live node or adapter.

Request Flow

sequenceDiagram
    participant Client as Client / AI Agent
    participant Gateway as API Gateway
    participant BTX as BTX Node or Mock
    participant API as Protected API

    Client->>Gateway: POST /btx/challenge
    Gateway->>BTX: Request MatMul service challenge
    BTX-->>Gateway: Challenge payload
    Gateway-->>Client: Challenge payload
    Client->>Client: Solve MatMul challenge locally
    Client->>Gateway: GET /protected/demo with x-btx-proof
    Gateway->>BTX: Redeem proof
    BTX-->>Gateway: Valid or invalid
    Gateway->>API: Allow request if valid
    API-->>Client: Protected response

Loading

Project Status

Status: experimental engineering research.

Use this repository to evaluate protocol shape, integration ergonomics, security assumptions, and operational cost. Do not treat it as a production access-control system without independent review, replay protection, abuse testing, live BTX node compatibility testing, and a clear failure policy.

Development

pnpm typecheck
pnpm test
pnpm benchmark:mock
python3 -m compileall -q examples/fastapi-gateway/app

License

MIT