Tyrpay Buyer Skill

Buyer-side TyrPay workflow for LLM agents. Create tasks, optionally wait for seller commitment, fund tasks explicitly, monitor settlement, and request refunds.

Use this skill when an agent needs to act as the buyer in a TyrPay payment flow. It assumes the runtime already has a configured BuyerSdk and access to the @tyrpay/buyer-skill tool set.

Quick Start

1. Install @tyrpay/buyer-skill, @tyrpay/buyer-sdk, and a storage adapter.
2. Construct BuyerSdk with a signer, settlement address, and storage adapter.
3. Register createBuyerTools(sdk) with your tool-calling runtime.
4. Call tyrpay_ready before the first paid workflow.
5. Use tyrpay_post_task with expectations for the default flow, or createOnly: true plus tyrpay_fund_task (with expectations) for explicit control.

When To Use

• The agent is responsible for creating and funding a TyrPay task.
• The agent must enforce buyer-side commitment expectations before payment is locked.
• The agent needs structured task state that is safe to show to an end user.
• The buyer workflow must stay non-blocking and recover cleanly after seller-response timeouts.

Workflow

1. Run tyrpay_ready to verify signer and provider connectivity.
2. Call tyrpay_post_task with expectations describing the acceptable commitment terms.
3. If you need explicit orchestration, set createOnly: true (no expectations needed at creation).
4. When the seller commitment is ready, call tyrpay_fund_task with expectations to validate and fund.
5. Use tyrpay_check_task or tyrpay_list_tasks to monitor progress.
6. If proof submission or verification stalls past protocol timeouts, call tyrpay_refund_task.

Mandatory Expectations

• expectations is required on every funding path. tyrpay_fund_task always requires it. tyrpay_post_task requires it unless createOnly: true.
• The on-chain protocol does not enforce that the seller's commitment matches the buyer's requirements. The chain only records the commitment; it does not validate host, path, models, minimum usage, verifier, or deadline against the buyer's intent.
• The skill layer rejects any funding call that omits expectations, preventing the agent from locking funds under unintended terms.

Tooling Notes

• All tools reject malformed inputs with structured BuyerSkillToolError errors.
• tyrpay_post_task returns timedOut: true instead of throwing when seller wait time expires after task creation.
• tyrpay_fund_task validates the commitment once, then funds without a second redundant validation pass.
• Buyer-facing statuses include VERIFIED_PASS and VERIFIED_FAIL when a verification report is available.

Resources

• references/tool-reference.md for the tool contract and status model.