# TickLogicX

**Ask TickLogic's on-chain gate whether an agent's spend would be allowed — and if not, exactly why.**

A remote [MCP](https://modelcontextprotocol.io) server (Streamable HTTP) that any
agent can call. It holds **no keys** and lands **nothing**: it builds the real
`execute` instruction and runs it through `simulateTransaction` against the
[TickLogic](https://ticklogic.xyz) gate deployed on Solana **devnet**. Same
programs, same policy bytecode, same verdict — it just never lands.

> A governed wallet can't be published as a service. A `pay` tool spends from the
> operator's vault with the operator's agent key, so exposing it would mean handing
> strangers the treasury. TickLogicX inverts it: read-only, keyless, and callable
> by anyone.

## Run

```bash
npm install
npm start          # POST http://localhost:8402/mcp · GET /health
```

No setup, no keypair, no funds: the tools default to the stable devnet demo
mandate, so a caller can try the service immediately.

| Env | Default |
|---|---|
| `PORT` | `8402` |
| `SOLANA_RPC_URL` | `https://api.devnet.solana.com` |
| `DEMO_MANDATE` | `GjSNUDdAWTYR2UQFroM2PaM9BLU3hnDjdGJVeojEcHcG` |

## Tools

### `mandate_inspect`
Status, per-tx and daily limits, amount spent today, allowed destination, expiry,
pinned policy program and vault balance for any mandate.

### `gate_check`
`ALLOWED`, or `BRAKED` with the exact policy reason.

```
BRAKED — the policy refused this spend: OVER_PER_TX (reason 8).
Nothing moved: this is a simulation against the deployed gate, not a transaction.

mandate       GjSNUDdAWTYR2UQFroM2PaM9BLU3hnDjdGJVeojEcHcG
policy        BMA1q23akKQZA1e48ivr2XZcFuoAi7KfcvGk49DSb3R4
policy return [allowed=false, reason=OVER_PER_TX]
policy cost   453 CU
total cost    6890 CU
limits        per-tx 1000 · daily 1000000000000 · spent today 1400
```

## Why the reason byte matters

On a real transaction the gate collapses **every** policy refusal into a bare
`DENIED(12)` — you learn that you were braked, not why. The policy CPI's return
value is `[verdict, reason]`, and in simulation that log survives, so `OVER_PER_TX`
and `DEST_NOT_ALLOWED` stay distinguishable. This service can tell a caller
something a landed transaction can't.

## Try it

```bash
curl -s -H 'content-type: application/json' \
     -H 'accept: application/json, text/event-stream' \
     -X POST http://localhost:8402/mcp \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
          "params":{"name":"gate_check","arguments":{"amount":5000}}}'
```

`700` is within the demo mandate (per-tx limit `1000`) and returns `ALLOWED`;
`5000` returns `OVER_PER_TX`; any other destination returns `DEST_NOT_ALLOWED`.

## Status

Devnet only, not audited. The gate, policy, referee and engagement programs live
in the TickLogic monorepo; this repo is only the read-only service in front of
them, built on [`@nzengi/ticklogic-sdk`](https://www.npmjs.com/package/@nzengi/ticklogic-sdk).

MIT.