TyrPay Seller Skill

Use this skill when an agent needs to act as the seller in a TyrPay payment flow.

It assumes the runtime already has a configured SellerAgent, a readable settlement

contract, and access to the @tyrpay/seller-skill tool set.

Quick Start

1. Install @tyrpay/seller-skill, @tyrpay/seller-sdk, a storage adapter, and a zkTLS adapter.
2. Construct SellerAgent with a signer, settlement address, chain ID, storage adapter, and zkTLS adapter.
3. Register createSellerTools({ agent, contract, verifierSignerAddress }) with your tool-calling runtime.
4. Call tyrpay_ready before the first task workflow.
5. For 0G TeeTLS/TeeML work, call tyrpay_discover_model_endpoint with the target model.
6. Use tyrpay_accept_task when you receive a taskId from a buyer.

When To Use

• The agent is responsible for accepting and executing TyrPay tasks as a seller.
• The agent must produce zkTLS-backed proofs of upstream API calls.
• The agent needs structured task state that is safe to show to an end user.
• The seller workflow must remain non-blocking and recoverable after network interruptions.
• When using 0G TeeTLS, the seller can only commit to the actual endpoint and

model resolved by the 0G TeeTLS adapter/service metadata. Do not commit to a

generic upstream endpoint or different model name.

• When only the model is known, use tyrpay_discover_model_endpoint to find a

reachable TeeTLS/TeeML endpoint before committing.

Workflow

1. Run tyrpay_ready to verify signer access and storage adapter connectivity.
2. For 0G TeeTLS/TeeML, call tyrpay_discover_model_endpoint and keep the recommended endpoint.
3. When a buyer shares a taskId, call tyrpay_accept_task with your execution terms.
4. Wait for the buyer to fund the task (poll with tyrpay_check_settlement).
5. Once funded, call tyrpay_execute_task for each required upstream API call.
6. Collect the returned receipts and call tyrpay_submit_proof with the full set.
7. Use tyrpay_check_settlement to monitor whether verification released payment.

Tooling Notes

• All tools reject malformed inputs with structured SellerSkillToolError errors.
• tyrpay_accept_task reads the on-chain task to derive buyer and verifier addresses.
• verifierSignerAddress is the registry-authorized verifier signer embedded

into ExecutionCommitment.verifier; it is not a settlement contract,

verifier registry, service URL, or verifier service contract address.

• The readable settlement contract must expose getTask(bytes32) with the

current TyrPaySettlement.Task field order:

taskId, taskNonce, buyer, seller, token, amount, deadlineMs,

requiredMinUsage, requiredModelsHash, commitmentHash, commitmentURI,

fundedAtMs, proofBundleHash, proofBundleURI, proofSubmittedAtMs,

reportHash, settledAtMs, refundedAtMs, status.

• tyrpay_execute_task requires the commitment object returned by tyrpay_accept_task.
• tyrpay_submit_proof requires all receipts collected from tyrpay_execute_task calls.
• For provider "0g-teetls", commitment.target.host/path must match the

resolved 0G endpoint, method must be POST, and allowedModels must include

the model returned by 0G service metadata. Forward the recommended

providerOptions from tyrpay_discover_model_endpoint to tyrpay_execute_task.

• Seller-facing statuses include PAID on successful settlement and NOT_PAID_REFUNDED on refund.

Failure Diagnosis

• If the task exists, seller address matches, and buyer has funded but status or

commitment fields look wrong, first inspect the ABI used for getTask(). A

stale ABI or positional mapping can shift fields and make seller-skill parse

commitmentHash, timestamps, or status from the wrong slot.

• Do not use MemoryStorageAdapter for a real multi-party flow. It returns

memory:// URIs that only the same JavaScript process can read. Buyer and

verifier processes need persistent shared storage such as 0G, IPFS, or HTTP.

• A commitment hash mismatch means the full canonical ExecutionCommitment

object is different from the object originally submitted. Chain data alone is

insufficient to reconstruct it; fetch it from commitmentURI or ask the

creator for the exact object.

• ReclaimZkTlsAdapter needs @reclaimprotocol/zk-fetch,

@reclaimprotocol/js-sdk, credentials, and downloaded zk resources. Install

those optional peer dependencies in the runtime that constructs the adapter.

Windows runtimes must keep Reclaim TEE mode disabled.

Resources

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