Get started

Quickstart for agents

Connect an agent to your account so it can call a Txpass-enabled API (today: the ImprintAI Provenance API, product imprintai-api) without an API key. It takes one command on the agent's machine and one signature from you (passkey by default; wallet optional).

What you need

• A Txpass account: sign in at /account with a passkey (or an optional Yours / BRC-100 wallet). See passkeys, devices and team members.
• Node.js 20 or later on the agent's machine.
• The txpass-agent CLI (below).

1. Install the CLI

npm i -g @txpass/agent
txpass-agent --help

On Windows (PowerShell), quote the package name:

npm i -g "@txpass/agent"

@txpass/agent is early access: expect changes between 0.x versions, and pin a version (for example npm i -g @txpass/agent@0.1.5) if you script it.

2. Connect

On the agent's machine:

txpass-agent connect imprintai-api

If the agent has no key yet, one is created and stored in ~/.txpass-agent/agent-key.json (readable only by you). The CLI prints a link and a code:

Connect this agent to imprintai-api

  1. Open this link and sign in (passkey, or optional wallet):
       https://txpass.app/account/connect?r=56ca99916f434884301a45639dd2780d
  2. Check the code on that page matches:  CFBF-BVNW
  3. Approve with one signature (or Deny).

Waiting for approval… (Ctrl-C to stop; the request then simply expires)

By default the agent asks for the product's recommended routes (for ImprintAI: POST /api/imprint and GET /api/status/:jobId). To ask for something else, list every route you need:

txpass-agent connect imprintai-api --scopes "POST /api/imprint,GET /api/status/:jobId,POST /api/log" --label "build-box / imprint-bot"

3. Approve in your browser

Open the link. On the approval screen:

1. Sign in with your passkey (or optional wallet) if you haven't yet.
2. Check the code matches the terminal exactly. Only approve a request you started yourself.
3. Choose where the agent goes:
   • A new policy: untick any routes the agent doesn't need, pick the session window (15–60 minutes, default 30), how long the policy lasts (default 90 days), the maximum number of agents and sessions per agent per day.
   • An existing policy for the same API.
4. Click Approve (one signature), or Deny (no signature needed).

The link on its own grants nothing: only your signature does. The request expires after 15 minutes and can be used once.

The CLI then prints Approved. and saves the membership in ~/.txpass-agent/policy.json. It also shows the API origins the agent may call (https://imprintai.link for imprintai-api). They come from the publisher's registration with Txpass, so there is nothing to configure. txpass-agent config --add-api-base https://… is only an optional local addition, for example for a dev server.

4. Use it

txpass-agent status --probe        # mints a session and shows scope and expiry (never the token)

First see what the API takes. describe lists the routes, the publisher's docs link and example requests with ready-to-run commands (it needs no session):

txpass-agent describe imprintai-api

Then send a published example. --example uses the example's method, path and minimal body, so there is no JSON to quote:

txpass-agent request --example create                    # POST /api/imprint {"model":"txpass-test","type":"created","async":true}
txpass-agent request --example status --param jobId=JOB_ID   # GET /api/status/:jobId (or: --example status JOB_ID)

Your own body, on macOS / Linux / Git Bash:

txpass-agent request POST /api/imprint --json '{"model":"my-model","type":"created","async":true}'

On Windows PowerShell, --json '{...}' loses its inner double quotes on the way to the CLI, and the API then answers 400. Put the body in a file and use --json-file:

Set-Content -Encoding ascii -Path "$env:TEMP\body.json" -Value '{"model":"my-model","type":"created","async":true}'
txpass-agent request POST /api/imprint --json-file "$env:TEMP\body.json"

For Imprint, model is the only required field. Don't send workflow_id in tests: without previous_txid it can chain onto your latest record. Each create writes a real record and counts toward your usage.

The agent mints a fresh session when it needs one, keeps it in memory and adds it to requests itself. Tokens and keys are never printed.

Use it from an MCP client

txpass-agent mcp-config prints a ready-to-paste entry for Claude Desktop, Cursor or any MCP client. The server exposes three tools:

5. Remove or revoke

On your account page, under Agents → Agent policies:

• Remove one agent: it can't mint new sessions; your other agents keep working.
• Revoke policy: every agent in that policy stops getting sessions.

Removal stops new sessions immediately. The Txpass agent checks with Txpass before every write, so a removed agent stops at once. A session already issued can still be accepted by an API that verifies locally until it expires (at most the session window, 15–60 minutes).

Other ways to add an agent

• One-time code: create a policy on the account page, then paste the enrollment command it shows into the agent: txpass-agent policy enroll 'txpass:enroll?…' (single use, 15 minutes).
• By key: paste the agent's public key (txpass-agent pubkey) into Add agent by key, then run txpass-agent policy enroll --policy <policy id> on the agent.
• One-off delegation (advanced): sign a delegation for a single agent key; see delegation v1.

Troubleshooting

More detail: the agent signer spec (threat model, guardrails, configuration) and agent policies v1 (the connect flow, section 16).