Skip to content

AWS KMS setup

Signing with an AWS KMS key is the recommended custody for anything unattended or shared: the private key never leaves KMS — only 32-byte digests are sent to be signed — and there are no per-trade approvals. Prefer it over a raw PRIMEDELTA_MCP_PRIVATE_KEY on any real environment.

1. Create the signing key

The key must be asymmetric secp256k1: key spec ECC_SECG_P256K1, usage SIGN_VERIFY. Use one key per agent.

aws kms create-key \
  --key-spec ECC_SECG_P256K1 \
  --key-usage SIGN_VERIFY \
  --description "primedelta agent signer"
# note the KeyId / Arn from the output

2. Scope an IAM policy to that key

Grant only what signing needs — kms:Sign and kms:GetPublicKey — pinned to this key's ARN. Do not grant kms:CreateKey, kms:Decrypt, or a wildcard Resource.

{
  "Effect": "Allow",
  "Action": ["kms:Sign", "kms:GetPublicKey"],
  "Resource": "arn:aws:kms:<region>:<account>:key/<key-id>"
}

Attach it to the identity (user, role, or instance profile) the server runs as.

3. Fund and verify the derived address

The signing address is derived from the KMS public key (secp256k1 → Ethereum address). Read it (e.g. via the SDK's KmsSigner(...).address), fund it with limited funds, and complete its DID / KYC — see Log in & claim a Digital Identity. Without a minted DID, trades won't go through.

4. Configure the server

pip install "primedelta[kms]"          # boto3, for the KMS signer
export PRIMEDELTA_MCP_MODE=execute
export PRIMEDELTA_MCP_KMS_KEY_ID=<key-id-or-arn>
export PRIMEDELTA_MCP_KMS_REGION=<region>   # optional; else the default AWS region

Standard AWS credential resolution applies — environment variables, a shared profile, or an instance/task role. Then verify with the session status tool: signer should read kms. If it reads null, the key id isn't set.

Using KMS from the SDK directly

from primedelta import PrimeDelta, KmsSigner

signer = KmsSigner(key_id="arn:aws:kms:…", region_name="eu-central-1")
pd = PrimeDelta(signer=signer, web3_provider_url=RPC, network="testnet")
print(signer.address)     # fund + KYC this address
pd.login()

KmsSigner reads the public key once to derive the address, then signs each transaction digest inside KMS. It needs the [kms] extra (boto3).

Notes

  • One key per agent, so you can revoke or rotate a single agent without touching the others.
  • Rotate by creating a new key, funding + KYC'ing its address, and swapping PRIMEDELTA_MCP_KMS_KEY_ID.
  • The KMS key id/ARN is an identifier, not a secret — but the IAM credentials that can use it are. Guard those.

Also see Operator hardening.