Quickstart

Coming next. Everything here runs on the sandbox, on fake rails: no bank is called and no money moves. Nothing is live in production yet.

In five minutes you will: make a sandbox API key, register a seller agent and a buyer agent, authorise a mandate, pay a quote and verify the receipt offline. The examples use the Python SDK (sdks/python, package tatvapay); the TypeScript SDK has the same calls.

1. A sandbox key

In the app, open Developers → API keys and make a key. It starts with tpk_ and is shown once. Your servers send it as Authorization: Bearer tpk_….

2. Two agents

An agent passport is a name, a role and an Ed25519 public key. The private key stays with you.

from tatvapay import TatvaPay, keys

workspace = TatvaPay("http://localhost:8100", api_key="tpk_…")

seller_key = keys.generate_key()
keys.save_private_key(seller_key, "seller.jwk.json")
seller = workspace.register_agent(
    "Travel desk", keys.public_jwk(seller_key), role="seller", categories=["travel"],
    listed=True,
    offers=[{"sku": "airport_transfer", "name": "Airport transfer", "unit_paise": 150000}],
)

buyer_key = keys.generate_key()
keys.save_private_key(buyer_key, "buyer.jwk.json")
buyer = workspace.register_agent("Travel buyer", keys.public_jwk(buyer_key))

You can also register agents in Developers → Agent passports; the browser makes the key and saves the private half as a file.

3. A mandate

A mandate is the limit a person sets for one buyer agent: per payment, per period, which sellers, until when. Make it in the app (or ask for a draft with request_mandate), then authorise it: the one-time 2FA step. In the sandbox the code is shown to you.

4. Pay

agent = TatvaPay("http://localhost:8100", agent_id=buyer["id"],
                 private_key=keys.load_private_key("buyer.jwk.json"))
quote = agent.request_quote(seller["id"], sku="airport_transfer")
payment = agent.pay(quote["id"])     # settled, requires_approval or rejected
print(payment["status"])             # "settled": ₹1,500 is under the ₹2,000 always-ask limit

Every request the agent makes is signed (TatvaPay-Agent-Signature). Deterministic rules decide each payment; a model never does.

5. Verify the receipt

receipt = agent.get_receipt(payment["receipt_id"])
print(agent.verify_receipt(receipt).valid)   # True: checked offline with TatvaPay's public keys

See Verify receipts for what is checked.

Next

• Connect Claude Desktop and let Claude buy inside the mandate
• Accept agent payments as a seller
• Error codes and rule ids