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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Pay with Stripe Link over HTTP

> Let a shopper pay with their own Stripe Link wallet from a server in any language: offer Link, confirm the cart with the payment the shopper approved, and send Agentcard that approval encrypted.

Let a shopper pay with their own Stripe Link wallet, beside the card they saved with Agentcard or in its place. Your server signs the shopper in to Link and asks Link for each payment, so Agentcard never holds the shopper's Link sign-in. [Connecting Stripe Link](https://docs.agentcard.com/commerce-sdk/guides/connecting-a-link-wallet.md) covers the sign-in.

At a store's own checkout, Agentcard types a one-time card from Link into the store's payment form. To get that card, Agentcard needs two things from your server: the id of the payment the shopper approved in Link, and the shopper's Link access token. Your server encrypts both so that only the Agentcard service that types the card can read them. Agentcard's API passes the encrypted text along and cannot read it.

The Commerce SDK does the encryption for you with `sealLinkGrant`, as [Paying with Stripe Link](https://docs.agentcard.com/commerce-sdk/guides/paying-with-a-link-wallet.md) shows. From any other language, follow the steps on this page. Test values let you check your code byte for byte before a shopper ever pays, and a complete Python version is near the end.

> [!NOTE]
>
> Agentcard turns on Link payments for each company. Until they reach yours, a request with `payment_source: "link"` is refused with a `400` and charges nothing, so keep the card saved with Agentcard as the shopper's way to pay:
>
> ```json theme={null}
> { "error": "Invalid enum value. Expected 'vault', received 'link'", "code": "invalid_request", "hint": "POST /buy { \"ask\": \"order sushi from DoorDash to my place\" }" }
> ```
>
> A hotel, a rental car or a flight booked through Agentcard takes Link as well, with one approval in Link for each booking at its quoted total.

## Offer Stripe Link

Name the ways to pay you offer on every request to `POST /buy`, in the order the shopper sees them. `vault` is the card the shopper saved with Agentcard, and `link` is their Stripe Link wallet. While the shopper pays with Link, also send `payment_source: "link"` and their Link spending limits:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user-42",
    "ask": "a set of picardie tumblers from duralexusa.com",
    "wallets": ["vault", "link"],
    "last_used_first": false,
    "payment_source": "link",
    "link_limits": { "per_purchase_cents": 50000, "daily_remaining_cents": 120000, "monthly_remaining_cents": null }
  }'
```

| Field | What it carries |
| - | - |
| `wallets` | The ways to pay you offer: `["vault"]`, `["link"]`, `["vault", "link"]` or `["link", "vault"]`. Each one appears once. |
| `last_used_first` | `true` puts the way the shopper paid last ahead of your order. |
| `payment_source` | `link` while the shopper pays with Link. Agentcard then skips the step where the shopper saves a card. |
| `link_limits` | The shopper's own limits in Link, in cents: `per_purchase_cents`, `daily_remaining_cents` and `monthly_remaining_cents`, each `null` when Link sets none. Agentcard keeps each cart within them. |
| `link_payment` | Sent only with a confirm: the Link payment the shopper approved, as the next section shows. |

An answer with carts to pay lists each way to pay you offer, and whether it can pay those carts:

```json theme={null}
{
  "wallets": [
    { "wallet": "vault", "fits": true, "reason": null, "reason_text": null, "last_used": false },
    { "wallet": "link", "fits": false, "reason": "over_limit", "reason_text": "Over Link's limit", "last_used": true }
  ]
}
```

Show a way to pay with `fits: false` as a disabled button beside its `reason_text`. Agentcard leaves out a way to pay that a store refuses outright. The `vault` entry carries `setup_needed: true` when the shopper has no card saved yet.

| `reason` | What it means |
| - | - |
| `store_cannot_take_link` | Stripe Link can't pay for this order yet. |
| `over_limit` | A store's cart costs more than one Link payment covers. |
| `over_daily_limit` | The carts together cost more than the shopper's Link wallet can still spend today. |
| `over_monthly_limit` | The carts together cost more than the shopper's Link wallet can still spend over 30 days. |
| `ships_outside_us_canada` | The order ships outside the US and Canada, where Link does not pay. |

## Confirm with the Link payment

Once the shopper says yes, ask Link for a payment of the most the cart can cost, one for each store, and wait until the shopper approves it in Link. Then confirm that store's cart with the approved payment: its `conversation_id`, the cart's `hash` in `confirm`, and the payment's id, amount and currency in `link_payment`:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_...",
    "external_user_id": "user-42",
    "confirm": "5b1e7c0d93a2f486",
    "payment_source": "link",
    "link_payment": { "spend_request_id": "lsrq_...", "amount_cents": 2133, "currency": "usd" }
  }'
```

Agentcard answers `202` with `status: "link_seal_needed"` and a `link_seal` object. `link_seal.binding` describes the payment Agentcard is about to make: which approval, which checkout, which store, how much, and until when. `seal_by` is the time your encrypted approval has to arrive by:

```json theme={null}
{
  "status": "link_seal_needed",
  "conversation_id": "conv_...",
  "link_seal": {
    "approval_id": "tcard_ninHixKD5dnwW0pR",
    "key_id": "tk_1HFMkfLE99W7RUUq",
    "binding": {
      "authorization": "tcard_ninHixKD5dnwW0pR",
      "session": "kern_sess_01",
      "origin": "https://duralexusa.com",
      "amountCents": 2133,
      "currency": "usd",
      "expiresAt": 1763316000000
    },
    "seal_by": "2026-11-16T18:00:00.000Z"
  }
}
```

Agentcard refuses a Link confirm for a cart Link cannot pay, and charges nothing:

```text theme={null}
409
{"error":"link_payment_unavailable","code":"link_payment_unavailable","message":"This cart can't be paid with Stripe Link yet. Nothing was charged. Keep the cart; the shopper can pay another way."}
```

Cancel the payment in Link, and offer the card saved with Agentcard for that cart.

## Check the payment first

Encrypt the shopper's approval only when `binding` describes the payment the shopper approved in Link. Agentcard pays exactly what `binding` describes, so encrypting for any other payment would let money go somewhere the shopper did not approve. Check every line below, and encrypt nothing when one fails:

| Check | Passes when |
| - | - |
| The approval | `binding.authorization` equals `link_seal.approval_id`. |
| The store | `binding.origin` is `https`, on the same port as the store the shopper approved in Link, and its host is that store's host, or that host with `www.` added or removed. |
| The amount | `binding.amountCents` is at most the amount the shopper approved. |
| The currency | `binding.currency` is the approved currency, in lower case. |
| The time | `binding.expiresAt`, in milliseconds since 1970, is still in the future. |

When a check fails, cancel the payment in Link and encrypt nothing. Agentcard charges nothing, and the shopper can pay for that cart with the card saved with Agentcard.

## Keep Agentcard's key in your code

Encrypt only to a public key you keep in your own code. Copy this table into your server:

| Key id | Public key, raw uncompressed P-256, base64url |
| - | - |
| `tk_1HFMkfLE99W7RUUq` | `BLfoRiKCW_9AsWsUCvTMN_0bXgah5n6m-NJgV69F7i-1nfwxVDB8c9LeqeMSAIEo_yoke1umnWa2T02WWUfnfmk` |

Look up `link_seal.key_id` in your table and encrypt to the key it finds. Never take a public key from an Agentcard answer: a key your server reads from the network could belong to anyone, and only the Agentcard service that types the card can read text encrypted to a key from this table.

Agentcard adds a new key to this table, beside the current one, before the service starts using it. Add each new key to your table when it appears here. A confirm that names a key id your table does not hold gets nothing from you: cancel the payment in Link. Agentcard charges nothing, and the shopper can pay with the card saved with Agentcard.

## Encrypt the approval

Encrypt once for each confirm, with a key pair you make for that one message:

1. Write the approval as compact JSON, with `kind`, `spend_request_id` and `access_token` in that order: `{"kind":"link","spend_request_id":"lsrq_...","access_token":"liat_..."}`. It is at most 4,096 bytes.
2. Write the additional data as a compact JSON array in this order: `["agentcard.typed-card",1,key_id,authorization,session,origin,amountCents,currency,expiresAt]`. `key_id` is `link_seal.key_id`, and the rest come from `link_seal.binding`. Copy each string as it is, and write each number as an integer with no decimal point.
3. Make a new P-256 key pair. Use it for this one message and then discard it.
4. Run ECDH between your new private key and Agentcard's public key. The shared secret is the 32-byte x-coordinate.
5. Derive a 32-byte key with HKDF-SHA-256. The input is the shared secret. The salt is your new public key followed by Agentcard's public key, each as its 65-byte uncompressed point, 130 bytes together. The info is the ASCII text `agentcard typed link grant v1`.
6. Encrypt the approval with AES-256-GCM under that key, with a random 12-byte IV and the additional data from step 2. Keep the 16-byte tag at the end of the ciphertext.
7. Write the envelope.

Every value in the approval and in `binding` is ASCII, as the table below shows. Write both JSON texts with no spaces, and escape only `"` as `\"` and `\` as `\\`. Write `/`, `<`, `>` and `&` as they are. Go's `json.Marshal` writes `<`, `>` and `&` as `<` escapes, so use a `json.Encoder` with `SetEscapeHTML(false)` and trim its trailing newline, or build the two strings by hand. The additional data has to match Agentcard's spelling byte for byte, or Agentcard cannot read the message.

| Value | Accepted form |
| - | - |
| `spend_request_id` | 6 to 64 letters, digits or `_`. |
| `access_token` | 1 to 3,900 printable ASCII characters, `!` to `~`, no spaces. |
| `key_id` | 1 to 64 letters, digits, `_`, `.` or `-`. |
| `authorization` | 8 to 64 letters, digits, `_` or `-`. |
| `session` | 1 to 128 letters, digits, `_`, `.`, `:` or `-`. |
| `origin` | An `https` origin as a browser writes it: lower case, no path, no trailing slash, no `:443`. |
| `currency` | Three lower-case letters. |
| `amountCents`, `expiresAt` | Positive integers no larger than 9,007,199,254,740,991. |

A value outside these forms is one Agentcard never sends: encrypt nothing, and cancel the payment in Link.

```json theme={null}
{ "v": 1, "kind": "link", "kid": "tk_1HFMkfLE99W7RUUq", "epk": "BIck...", "iv": "obLD1OX2BxgpOktc", "ct": "PRem..." }
```

| Field | Value |
| - | - |
| `v` | The number `1`. |
| `kind` | The text `link`. |
| `kid` | The key id you encrypted to. |
| `epk` | Your new public key, as its 65-byte uncompressed point starting with `0x04`. |
| `iv` | The 12-byte IV. |
| `ct` | The ciphertext with its 16-byte tag at the end. |

Write every byte field in base64url with no `=` padding, as RFC 4648 section 5 describes. Python's `base64.urlsafe_b64encode` adds padding, so strip the trailing `=` signs. The envelope's own JSON can list its fields in any order and with any spacing.

## Send the encrypted approval

Post the envelope to the approval named in `link_seal.approval_id`, with the same access token and `external_user_id` as the confirm, before `seal_by`:

```bash theme={null}
curl https://api.agentcard.sh/buy/v1/link-seals/tcard_ninHixKD5dnwW0pR \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "user-42",
    "sealed": { "v": 1, "kind": "link", "kid": "tk_1HFMkfLE99W7RUUq", "epk": "BIck...", "iv": "obLD1OX2BxgpOktc", "ct": "PRem..." }
  }'
```

```json theme={null}
{ "status": "sealed" }
```

Agentcard then types Link's one-time card into the store's checkout and pays at the store's total. A `purchase.message` tells you how the order went, and names the Link payment and whether the store charged it, as [`facts.linkPayment`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#shopperfacts) reads it. Keep the shopper's Link access token out of your logs, and send it nowhere but inside the envelope.

## Read a refusal

Agentcard refuses an envelope it cannot use, and charges nothing. An envelope whose parts are padded, in standard base64 or the wrong length is refused the moment you post it:

```json theme={null}
{ "error": "The seal is not a Link grant sealed to this approval's key.", "code": "link_seal_invalid" }
```

| Status | `code` | What it means | What to do |
| - | - | - | - |
| `400` | `link_seal_invalid` | The envelope is not encrypted to the approval's key: a field is missing or extra, a byte field is padded or the wrong length, or `kid` is another key. | Fix your code against the test values below. Until `seal_by`, post a corrected envelope to the same approval. After it, cancel the payment in Link, ask for the cart again, and confirm the new cart. |
| `404` | `link_seal_not_found` | No Link approval with this id waits for this shopper in your app. | Post with the same access token and `external_user_id` as the confirm. |
| `409` | `link_seal_answered` | The envelope already arrived, or its payment ended. | Read the conversation for how the order went. Post nothing more. |
| `410` | `link_seal_expired` | The envelope came after `seal_by`, and the waiting checkout ended. | Cancel the payment in Link, ask for the cart again, and confirm the new cart. |

## Encrypt in Python

Save the module below as `agentcard_link_seal.py`. The module encrypts the approval with the `cryptography` package, checks `binding` against the payment the shopper approved, and holds Agentcard's public key in its own text. Install the package with `pip install cryptography`, and run the module on Python 3.9 or later.

```python theme={null}
"""Seal a shopper's Stripe Link grant for Agentcard's typing service, from a server that does not run the Commerce SDK.

This is the reference the Purchase API docs publish (purchase-api/link-seal). It makes the same envelope, byte for byte,
as the Commerce SDK's sealLinkGrant, and the typing service is the only party that can open it: your server seals,
Agentcard's API stores and forwards the ciphertext, and only the typing service reads the Link access token.

    ECDH P-256 with a fresh key pair per seal
    HKDF-SHA-256(secret, salt = ephemeral public key || service public key, info = "agentcard typed link grant v1", 32 bytes)
    AES-256-GCM, 12-byte IV, 16-byte tag appended, additional data = a compact JSON array of the key id and the binding
    every byte string base64url with no padding

Needs the `cryptography` package (pip install cryptography). Python 3.9 or later.
"""
from __future__ import annotations

import base64
import json
import os
import re
import time
from typing import Any, Mapping, Optional
from urllib.parse import urlsplit

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat

# The typing service's public keys, by key id: raw uncompressed P-256 points, base64url. Pin these in your code and seal only
# to a key id listed here. A confirm that names a key id you do not pin means Agentcard rotated the service's key: update
# this table from the docs page, never from the confirm's answer.
TYPER_KEYS: Mapping[str, str] = {
    "tk_1HFMkfLE99W7RUUq": "BLfoRiKCW_9AsWsUCvTMN_0bXgah5n6m-NJgV69F7i-1nfwxVDB8c9LeqeMSAIEo_yoke1umnWa2T02WWUfnfmk",
}

LABEL = b"agentcard typed link grant v1"
MAX_GRANT_BYTES = 4096
_SPEND_REQUEST_ID = re.compile(r"[A-Za-z0-9_]{6,64}")
_ACCESS_TOKEN = re.compile(r"[\x21-\x7e]{1,3900}")
_AUTHORIZATION = re.compile(r"[A-Za-z0-9_-]{8,64}")
_SESSION = re.compile(r"[A-Za-z0-9_.:-]{1,128}")
_KEY_ID = re.compile(r"[A-Za-z0-9_.-]{1,64}")
_CURRENCY = re.compile(r"[a-z]{3}")
_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
_MAX_SAFE_INTEGER = 2**53 - 1


class LinkSealError(Exception):
    """Why nothing was sealed. The message never holds a byte of the token or a key."""

    def __init__(self, code: str) -> None:
        super().__init__(code)
        self.code = code


def b64url(data: bytes) -> str:
    """base64url with no padding: the only spelling Agentcard takes."""
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")


def from_b64url(text: str) -> bytes:
    """The bytes of a canonical unpadded base64url string; ValueError for any other spelling."""
    if not isinstance(text, str) or not text or not re.fullmatch(r"[A-Za-z0-9_-]+", text) or len(text) % 4 == 1:
        raise ValueError("not base64url")
    data = base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
    if b64url(data) != text:
        raise ValueError("not canonical base64url")
    return data


def _safe_positive(value: Any) -> bool:
    return type(value) is int and 0 < value <= _MAX_SAFE_INTEGER


def _origin_ok(value: Any) -> bool:
    """An https origin as a browser writes it (lower case, no path, no default port), or loopback http for local tests."""
    if not isinstance(value, str) or not value.isascii():
        return False
    parts = urlsplit(value)
    try:
        port = parts.port
    except ValueError:
        return False
    host = parts.hostname
    if parts.scheme not in ("https", "http") or not host or "@" in parts.netloc or parts.path or parts.query or parts.fragment:
        return False
    if parts.scheme == "http" and host not in _LOOPBACK:
        return False
    default = 443 if parts.scheme == "https" else 80
    written = f"[{host}]" if ":" in host else host
    rebuilt = f"{parts.scheme}://{written}" + (f":{port}" if port is not None and port != default else "")
    return rebuilt == value


def check_binding(binding: Mapping[str, Any]) -> dict:
    """The binding from the confirm's `link_seal.binding`, checked part by part. Raises link_seal_binding_invalid."""
    if not isinstance(binding, Mapping):
        raise LinkSealError("link_seal_binding_invalid")
    b = {k: binding.get(k) for k in ("authorization", "session", "origin", "amountCents", "currency", "expiresAt")}
    if not (
        isinstance(b["authorization"], str) and _AUTHORIZATION.fullmatch(b["authorization"])
        and isinstance(b["session"], str) and _SESSION.fullmatch(b["session"])
        and _origin_ok(b["origin"])
        and _safe_positive(b["amountCents"])
        and isinstance(b["currency"], str) and _CURRENCY.fullmatch(b["currency"])
        and _safe_positive(b["expiresAt"])
    ):
        raise LinkSealError("link_seal_binding_invalid")
    return b


def additional_data(binding: Mapping[str, Any], kid: str) -> bytes:
    """The bytes the seal is bound to: a JSON array in this fixed order, with no spaces."""
    b = check_binding(binding)
    parts = ["agentcard.typed-card", 1, kid, b["authorization"], b["session"], b["origin"], b["amountCents"], b["currency"], b["expiresAt"]]
    return json.dumps(parts, separators=(",", ":"), ensure_ascii=True).encode("ascii")


def grant_plaintext(spend_request_id: str, access_token: str) -> bytearray:
    """The sealed JSON: kind, spend_request_id, access_token, in that order, with no spaces."""
    if not (isinstance(spend_request_id, str) and _SPEND_REQUEST_ID.fullmatch(spend_request_id)
            and isinstance(access_token, str) and _ACCESS_TOKEN.fullmatch(access_token)):
        raise LinkSealError("link_seal_grant_invalid")
    text = json.dumps({"kind": "link", "spend_request_id": spend_request_id, "access_token": access_token}, separators=(",", ":"), ensure_ascii=True)
    plain = bytearray(text.encode("ascii"))
    if len(plain) > MAX_GRANT_BYTES:
        raise LinkSealError("link_seal_grant_invalid")
    return plain


def _recipient_point(public_key: str) -> bytes:
    try:
        raw = from_b64url(public_key)
    except ValueError:
        raise LinkSealError("link_seal_key_unknown") from None
    if len(raw) != 65 or raw[0] != 4:
        raise LinkSealError("link_seal_key_unknown")
    return raw


def seal_link_grant(
    spend_request_id: str,
    access_token: str,
    binding: Mapping[str, Any],
    kid: str,
    public_key: str,
    *,
    ephemeral_private_key: Optional[ec.EllipticCurvePrivateKey] = None,
    iv: Optional[bytes] = None,
) -> dict:
    """The envelope to post: {v, kind, kid, epk, iv, ct}. `ephemeral_private_key` and `iv` exist for the test vectors only;
    in production leave both out, so every seal has a fresh key pair and a fresh random IV."""
    if not isinstance(kid, str) or not _KEY_ID.fullmatch(kid):
        raise LinkSealError("link_seal_key_unknown")
    aad = additional_data(binding, kid)
    plain = grant_plaintext(spend_request_id, access_token)
    try:
        recipient_raw = _recipient_point(public_key)
        recipient = ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), recipient_raw)
        sender = ephemeral_private_key or ec.generate_private_key(ec.SECP256R1())
        sender_raw = sender.public_key().public_bytes(Encoding.X962, PublicFormat.UncompressedPoint)
        secret = sender.exchange(ec.ECDH(), recipient)
        key = HKDF(algorithm=hashes.SHA256(), length=32, salt=sender_raw + recipient_raw, info=LABEL).derive(secret)
        nonce = iv if iv is not None else os.urandom(12)
        if len(nonce) != 12:
            raise LinkSealError("link_seal_key_unknown")
        ct = AESGCM(key).encrypt(nonce, bytes(plain), aad)
    except LinkSealError:
        raise
    except Exception:
        raise LinkSealError("link_seal_key_unknown") from None
    finally:
        plain[:] = b"\0" * len(plain)
    return {"v": 1, "kind": "link", "kid": kid, "epk": b64url(sender_raw), "iv": b64url(nonce), "ct": b64url(ct)}


def binding_mismatch(link_seal: Mapping[str, Any], approved_store_url: str, approved_amount_cents: int, approved_currency: str,
                     now_ms: Optional[int] = None) -> Optional[str]:
    """Why the seal Agentcard asked for is not for the payment the shopper approved in Link, or None when it is: the binding
    names the approval Agentcard named, the store Link approved (its host or its www. form, over https), at most the
    approved amount, the same currency, and it has not ended."""
    binding = check_binding(link_seal.get("binding"))
    if binding["authorization"] != link_seal.get("approval_id"):
        return "authorization"
    store, origin = urlsplit(approved_store_url or ""), urlsplit(binding["origin"])
    base = lambda host: (host or "").lower().removeprefix("www.")  # noqa: E731
    if store.scheme != "https" or origin.scheme != "https" or (store.port or 443) != (origin.port or 443) or not store.hostname or base(store.hostname) != base(origin.hostname):
        return "store"
    if binding["amountCents"] > approved_amount_cents:
        return "amount"
    if binding["currency"] != approved_currency.lower():
        return "currency"
    if not binding["expiresAt"] > (now_ms if now_ms is not None else int(time.time() * 1000)):
        return "expired"
    return None


def seal_for_typer(link_seal: Mapping[str, Any], spend_request_id: str, access_token: str) -> dict:
    """Seals to the pinned key the confirm named. A key id this table does not pin is refused before anything is read."""
    key_id = link_seal.get("key_id")
    public_key = TYPER_KEYS.get(key_id) if isinstance(key_id, str) else None
    if public_key is None:
        raise LinkSealError("link_seal_key_unknown")
    return seal_link_grant(spend_request_id, access_token, link_seal.get("binding"), key_id, public_key)
```

Check the binding, then seal and post. A binding Agentcard never sends raises `LinkSealError`, as does a key id your table does not pin:

```python theme={null}
from agentcard_link_seal import binding_mismatch, seal_for_typer

link_seal = answer["link_seal"]
mismatch = binding_mismatch(link_seal, approved_store_url, approved_amount_cents, approved_currency)
if mismatch is None:
    sealed = seal_for_typer(link_seal, spend_request_id, link_access_token)
    # POST {"external_user_id": ..., "sealed": sealed} to /buy/v1/link-seals/<approval_id>
else:
    # Cancel the spend request in Link; the shopper can pay for the cart with the Vault.
    ...
```

## Check your code with test values

Each test value set below, called a vector, fixes the two values an encryption otherwise makes at random: the new key pair and the IV. Encrypt each vector's `grant`, the approval, to its `recipient` under its `binding`, with its `ephemeral` private key and its `iv`, and your code must produce its `envelope` exactly. The ephemeral private key is PKCS #8 DER in base64url: in Python, `load_der_private_key(from_b64url(key), password=None)`. Matching an envelope means each of its six fields holds the same value. The vectors also show `plaintext`, `additional_data`, `shared_secret_hex`, `salt` and `aes_key_hex`, so a mismatch tells you which step to look at.

Every private key here is a test key made for these vectors. The first vector is a plain approval. The second holds a quote, a backslash and a slash in the access token and a port in the origin, so it checks your JSON escaping. Both include the recipient's private key, so you can open them too.

```json theme={null}
{
  "name": "a plain grant to a test key",
  "recipient": {
    "kid": "tk_pj-P7ghORAVnGBtj",
    "publicKey": "BFoqU5IgLZIOPtx4l2PuGMaaeGgPijcPxdVVuQv-w3SjJ4Qdq0hB9pzArcxERYmSPZuW23rGITepmKKbzGZgkKc",
    "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgHS7QnYfVbQq2tCj8OwiF1NV0oKtEb_Ws6eg7jMyuxTWhRANCAARaKlOSIC2SDj7ceJdj7hjGmnhoD4o3D8XVVbkL_sN0oyeEHatIQfacwK3MREWJkj2bltt6xiE3qZiim8xmYJCn"
  },
  "ephemeral": {
    "publicKey": "BIckNngpyCc13FO1Ez_fqXQ1vJrclrFS_2p3MwhcXKW3nf0GAjQqmTCZXGP99oRXY0cT8Cdaz5y8pTsbbb4KumY",
    "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgAojlKmIFFVPh-4HscFAdFsw0L7p3FvJSMVD8ZvgtrNyhRANCAASHJDZ4KcgnNdxTtRM_36l0Nbya3JaxUv9qdzMIXFylt539BgI0KpkwmVxj_faEV2NHE_AnWs-cvKU7G22-Crpm"
  },
  "iv": "obLD1OX2BxgpOktc",
  "binding": {
    "authorization": "tcard_vector000000001",
    "session": "kern_sess_vector01",
    "origin": "https://store.example",
    "amountCents": 2599,
    "currency": "usd",
    "expiresAt": 1893456000000
  },
  "grant": {
    "kind": "link",
    "spend_request_id": "lsrq_vector000001",
    "access_token": "liat_frozen_vector_token_not_a_real_one_0001"
  },
  "plaintext": "{\"kind\":\"link\",\"spend_request_id\":\"lsrq_vector000001\",\"access_token\":\"liat_frozen_vector_token_not_a_real_one_0001\"}",
  "additional_data": "[\"agentcard.typed-card\",1,\"tk_pj-P7ghORAVnGBtj\",\"tcard_vector000000001\",\"kern_sess_vector01\",\"https://store.example\",2599,\"usd\",1893456000000]",
  "shared_secret_hex": "f99dc4b56f54e02c5284d732d16f11f9489a8d45988c525570cef38c3d734ec3",
  "salt": "BIckNngpyCc13FO1Ez_fqXQ1vJrclrFS_2p3MwhcXKW3nf0GAjQqmTCZXGP99oRXY0cT8Cdaz5y8pTsbbb4KumYEWipTkiAtkg4-3HiXY-4Yxpp4aA-KNw_F1VW5C_7DdKMnhB2rSEH2nMCtzERFiZI9m5bbesYhN6mYopvMZmCQpw",
  "aes_key_hex": "070367662c9c50133398ae1a304fb388d2468f9c52969e9b69fce068685cb8a8",
  "envelope": {
    "v": 1,
    "kind": "link",
    "kid": "tk_pj-P7ghORAVnGBtj",
    "epk": "BIckNngpyCc13FO1Ez_fqXQ1vJrclrFS_2p3MwhcXKW3nf0GAjQqmTCZXGP99oRXY0cT8Cdaz5y8pTsbbb4KumY",
    "iv": "obLD1OX2BxgpOktc",
    "ct": "PRemvnUVTCr7Yx41qIRlHUPk4El_0in7-9EsT4nTujwZdJRar4-LGkNg-f4aFujkrkLWXzLLfPh2rChVY-PR9IjACTh8fIyBpgZ1eLE769IdwUJZrfxTB3mHEI-7_GQ7XqOxoLwCJIhqcIGQapdlIN4G5Ndnt-SdevwLyrwCKaRlfvme"
  }
}
```

```json theme={null}
{
  "name": "an access token holding characters JSON escapes or some encoders escape, at an origin with a port",
  "recipient": {
    "kid": "tk_vector.two-2",
    "publicKey": "BJ8YIrJh6yOilDPcZi62d7QqaTFKzuWDOGipRBnYk18tgMGDfgzroxE502pJlOk4cjVF4O5i_xedoiav8a6a-g4",
    "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgRtMf6mJzA0FQbb2AdD85TkVsWUTtR8x0meQyd2UKXqOhRANCAASfGCKyYesjopQz3GYutne0KmkxSs7lgzhoqUQZ2JNfLYDBg34M66MROdNqSZTpOHI1ReDuYv8XnaImr_GumvoO"
  },
  "ephemeral": {
    "publicKey": "BP28E6W9GNYJjKc15EJaCkMTj4lRslC1OajKyzboTpb_H_kj0H9ewc2suoqEdZza7SEVtcT9ChBhIZqBNcU5x9g",
    "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgG7r2ulpMfg5gLZyXrDPzV953qpgz6wkHOBRO4Kfikb2hRANCAAT9vBOlvRjWCYynNeRCWgpDE4-JUbJQtTmoyss26E6W_x_5I9B_XsHNrLqKhHWc2u0hFbXE_QoQYSGagTXFOcfY"
  },
  "iv": "hFZR4M1HbjbLfXmh",
  "binding": {
    "authorization": "tcard_Vector-0000002",
    "session": "kern:sess.vector_02",
    "origin": "https://shop.example:8443",
    "amountCents": 123456789,
    "currency": "eur",
    "expiresAt": 1924992000000
  },
  "grant": {
    "kind": "link",
    "spend_request_id": "lsrq_Vector_000002",
    "access_token": "liat_\"quoted\"\\back/slash~!@#$%^&*()+={}[]|:;<>,.?"
  },
  "plaintext": "{\"kind\":\"link\",\"spend_request_id\":\"lsrq_Vector_000002\",\"access_token\":\"liat_\\\"quoted\\\"\\\\back/slash~!@#$%^&*()+={}[]|:;<>,.?\"}",
  "additional_data": "[\"agentcard.typed-card\",1,\"tk_vector.two-2\",\"tcard_Vector-0000002\",\"kern:sess.vector_02\",\"https://shop.example:8443\",123456789,\"eur\",1924992000000]",
  "shared_secret_hex": "01775a0d2baf4e74d57eac7e48aed9bad520fdcb863db7d0c2c26fe4fd20c2ea",
  "salt": "BP28E6W9GNYJjKc15EJaCkMTj4lRslC1OajKyzboTpb_H_kj0H9ewc2suoqEdZza7SEVtcT9ChBhIZqBNcU5x9gEnxgismHrI6KUM9xmLrZ3tCppMUrO5YM4aKlEGdiTXy2AwYN-DOujETnTakmU6ThyNUXg7mL_F52iJq_xrpr6Dg",
  "aes_key_hex": "9335c60d80acfaa6248124ad975b617ce7e86c44825f9943afed3a0bc8ea5c13",
  "envelope": {
    "v": 1,
    "kind": "link",
    "kid": "tk_vector.two-2",
    "epk": "BP28E6W9GNYJjKc15EJaCkMTj4lRslC1OajKyzboTpb_H_kj0H9ewc2suoqEdZza7SEVtcT9ChBhIZqBNcU5x9g",
    "iv": "hFZR4M1HbjbLfXmh",
    "ct": "_MOEazzNv08hbCTFSMvAubcsZAPepCBGtCJBqMk7nq5q2Ea6wXd987ggMycPDI2baeaUygBVmvXztJLpfx1ZBenBDONAK-Mzx7s_r4VTKsZAZFjj1lVzog_yxTDnGvdpPdikPXO5c2H4XOiHeO5FQIPvQmmMNKW4NPLHpuVJkqdgsTxzFNxJrAp9bdFN"
  }
}
```

The third vector is encrypted to Agentcard's live key, which has no published private key. Check it by matching its envelope:

```json theme={null}
{
  "name": "sealed to the typing service's production key: check it by matching the envelope",
  "recipient": {
    "kid": "tk_1HFMkfLE99W7RUUq",
    "publicKey": "BLfoRiKCW_9AsWsUCvTMN_0bXgah5n6m-NJgV69F7i-1nfwxVDB8c9LeqeMSAIEo_yoke1umnWa2T02WWUfnfmk"
  },
  "ephemeral": {
    "publicKey": "BGStj9XY1IgzKNBLYvgZY_zKf9N3048afovf1AalRb7UQ1e-9DxNZcsywAAeVxQKPIHInX-g4tFOWLccQ817FYs",
    "privateKey": "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgaE6FctYT65NwN7OeftVPmQwcQcRQPYD0eqf7enhEh1ihRANCAARkrY_V2NSIMyjQS2L4GWP8yn_Td9OPGn6L39QGpUW-1ENXvvQ8TWXLMsAAHlcUCjyByJ1_oOLRTli3HEPNexWL"
  },
  "iv": "WOuy8MW8_4UzzQtw",
  "binding": {
    "authorization": "tcard_ProductionKey01",
    "session": "kern_sess_prodkey01",
    "origin": "https://www.store.example",
    "amountCents": 4999,
    "currency": "usd",
    "expiresAt": 1893456000000
  },
  "grant": {
    "kind": "link",
    "spend_request_id": "lsrq_prodkey000001",
    "access_token": "liat_frozen_vector_token_not_a_real_one_0003"
  },
  "plaintext": "{\"kind\":\"link\",\"spend_request_id\":\"lsrq_prodkey000001\",\"access_token\":\"liat_frozen_vector_token_not_a_real_one_0003\"}",
  "additional_data": "[\"agentcard.typed-card\",1,\"tk_1HFMkfLE99W7RUUq\",\"tcard_ProductionKey01\",\"kern_sess_prodkey01\",\"https://www.store.example\",4999,\"usd\",1893456000000]",
  "shared_secret_hex": "a2c897896da9d7b4e33ee557bbf2caafd998607a08043adb3d5abf9f39c4dd18",
  "salt": "BGStj9XY1IgzKNBLYvgZY_zKf9N3048afovf1AalRb7UQ1e-9DxNZcsywAAeVxQKPIHInX-g4tFOWLccQ817FYsEt-hGIoJb_0CxaxQK9Mw3_RteBqHmfqb40mBXr0XuL7Wd_DFUMHxz0t6p4xIAgSj_KiR7W6adZrZPTZZZR-d-aQ",
  "aes_key_hex": "4662a075a6d5dfe7b2e0936750ef021f7d9e5a513cdf5d461e47a9a7fb98f6f1",
  "envelope": {
    "v": 1,
    "kind": "link",
    "kid": "tk_1HFMkfLE99W7RUUq",
    "epk": "BGStj9XY1IgzKNBLYvgZY_zKf9N3048afovf1AalRb7UQ1e-9DxNZcsywAAeVxQKPIHInX-g4tFOWLccQ817FYs",
    "iv": "WOuy8MW8_4UzzQtw",
    "ct": "tREmETnviYwwTccc_LanGiNOQkM0dYEcxBkc6Asf9GfdLYelqTsYZcmO-ctBXb0bUJQnm4aAyfARnYU60Po9rU2zLFgpvQf9IC-dG3J2pT6WLU6dqLFVnsBFX54olO2t2O-ALfsXzYn6hS3eHs3focVtpE7yEF458P4j9YDi6UcgY_zEBQ"
  }
}
```

With real shoppers, never pass a fixed key or IV: make both fresh for every encryption.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.