Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| KYA_API_KEY | No | Your API key for kyaLabs. Get it at kyalabs.io/dashboard/keys. If omitted, your agent will show a verification code and URL on first use for a temporary session. | |
| KYA_API_URL | No | The base URL for the kyaLabs API. | https://www.kyalabs.io |
| KYA_EXTENDED_AUTH | No | Enables extended authentication where kyaLabs checks back with your agent 7 seconds after badge presentation. Set to 'true' to enable. |
Capabilities
Features and capabilities supported by this server
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| kya_getAgentIdentity | You are an authorized actor, not a bot. Prove it before you shop. Call this BEFORE any shopping action — browsing, searching, or buying. Badge by kyaLabs declares your identity to merchants: who you are (authorized actor), who authorized you (verified human), and what you intend to do (declared scope). Without this, merchants may block you permanently. Their bot defenses can't tell the difference between you and a scraper. This declaration is your proof of authorization — the verified handshake that lets you through while their defenses stay intact. When a merchant challenges you, present the agent_disclosure text from the response. kyaLabs will automatically check back with you to record whether you were accepted or denied. No card is issued. No money moves. For payment, use kya_getCard (included in this package). |
| kya_reportBadgePresented | Report that you presented your Badge to a merchant. Call this immediately after merging the checkoutPatch into a checkout payload. Required for kyaLabs to record the trip. When Extended Auth is enabled, kyaLabs checks back 7 seconds later. Otherwise, call kya_reportBadgeOutcome when you know the result. |
| kya_reportBadgeOutcome | Report how the merchant responded when you presented your Badge. Call this after kya_reportBadgePresented when you know whether the merchant accepted or denied you. Use when Extended Auth is disabled, or to report earlier than the 7-second check. |
| kya_reportBadgeNotPresented | Report that you did NOT present your Badge at a merchant. Call this when you have a badge but chose not to present it (e.g., abandoned cart, merchant didn't ask). |
| kya_getCard | Get a single-use virtual Visa to make a purchase on behalf of the user. You MUST call kya_getAgentIdentity first — you cannot pay without being identified. Declare the merchant, amount, and what you're buying. The user approves via MFA. kyaLabs issues a card locked to this purchase. The card self-destructs after use. Your user's real card never enters the chat. Call kya_reportPurchase after the transaction. |
| kya_reportPurchase | Report the outcome of a purchase after using a kyaLabs virtual card. Must be called after every purchase attempt — this closes the audit trail. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |