> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Agent signer

> Sign SohoPay Protocol V2 vouchers and proof-of-possession with the agent workload key.

`@sohopay/agent-signer` is the client library for the agent's Ed25519 key. It does not call MCP, and it does not hold a borrower key. Policy and settlement stay on the server.

```bash
npm install @sohopay/agent-signer
```

```ts
import {
  generateWorkloadKey,
  signPoP,
  signVoucher,
  buildPaymentSignatureHeader,
} from "@sohopay/agent-signer";

const key = generateWorkloadKey();

const { pop_signature } = signPoP(
  {
    borrowerId,
    terminalId,
    jkt: key.jkt,
    nonce,
    iat: Math.floor(Date.now() / 1000),
  },
  key.privateKeyBase64Url,
);

const { signature } = signVoucher({
  voucher,
  signing,
  privateKeyBase64Url: key.privateKeyBase64Url,
  publicJwk: key.publicJwk,
});

const { headerName, headerValue } = buildPaymentSignatureHeader(
  prepareResponse,
  signature,
);
```

`generateWorkloadKey` runs once per terminal. Persist the private key on the host and register the public key with `register_agent_workload_key`.

`signVoucher` checks the payment id and the key thumbprint, and it rejects a JWK that includes private material (`d`). Failures throw `SignerError` with a stable `code`. Pass the `signing` block from the prepare response through unchanged. The library will not sign under a scheme outside its allowlist.

`headerName` is `PAYMENT-SIGNATURE`. Send `headerValue` on the retry to the merchant.

> [!NOTE]
>
> There is no `@sohopay/sdk` REST client and no `sohopay` package on PyPI. Python hosts shell out to this library or port the same signing rules. Do not hand-roll the voucher bytes from an old doc.

## Next steps

> [card] [Key management](/guides/key-management.md)
>
> Which key this library is allowed to hold.

> [card] [Payment flow](/guides/payment-flow.md)
>
> When to call signVoucher.
