How Seller Services Work

As a seller, a seller service is how you publish a resource, an MCP server, an API, a webpage, or a Fetch.ai agent, for buyer agents to reach. You configure how restrictive access to that resource is: what identity a buyer agent must disclose, and whether reaching it costs anything at all.

A seller agent publishes and owns each seller service. See Seller Guide for creating a seller agent.

The full flow

A seller service follows the same path whether or not it charges for access.

1. A buyer agent discovers your seller service, through the Skyfire Directory or another channel you point it to.
2. It creates a token for your seller service, specifying your service's ID in the request, which addresses the token to your seller agent.
3. It calls your service, passing that token in whichever header your backend expects, kyapay-token by convention.
4. Your service reads that header and admits the request once the token checks out.

Two types of setup

Operating as a seller involves setup on Skyfire, and setup in your own backend.

Skyfire provides the infrastructure; your backend provides the judgment. Verifying and charging a token is yours to implement, which is what lets you decide what counts as valid access and how much it costs.

Setup on Skyfire

This assumes you already have a seller agent. See Seller Guide for creating one.

Create your seller service

Click Create Service, then fill in the seller service details.

One seller agent can publish more than one seller service, each with its own price, accepted token types, and identity requirements.

Set identity requirements

This step is optional. Without identity requirements, any buyer agent with sufficient funds can transact with your seller service.

To require identity, declare which fields a buyer agent must include in its kya or kya-pay token, and which kinds of buyer agents you accept: individuals, organizations, or both. See Identity Fields for the fields you can require, and Know Your Agent (KYA) for how verification works.

Submit for approval

Skyfire reviews each seller service before buyer agents can create tokens for it. Review typically takes 48 hours. The review confirms that the seller service works and is configured correctly, so tokens created for it validate as expected once buyer agents start calling. Once approved, your seller service is discoverable in the Skyfire Directory.

Setup in your backend

A seller service is built to receive a token with every request.

Assign a token header

KYAPay tokens are standard signed JWTs. The standard is for buyer agents to send them in the kyapay-token header, so enforce that header on your service.

Older integrations, or older buyer agents, may still use the deprecated skyfire-pay-id header instead.

Enforce the dedicated kyapay-token header rather than reusing the standard Authorization header. Many services already use Authorization for their own authentication, and reusing it for KYAPay tokens can cause conflicts or unintended behavior.

Choose an integration path

Choose one of three integration paths below, depending on the level of control and security your service needs.

Other integration paths may be possible. Contact [email protected] to discuss your specific use case.

Verify, deliver, and charge

Whichever path you choose, three steps happen in order once a token reaches your service.

1. Verify the token. Confirm it is genuine and addressed to you before doing anything else. See Verify and Extract Data from Tokens and Handling Missing or Invalid Tokens for how to do so.
2. Deliver. Deliver the service, tool, or resource once the token passes verification. Delivering before charging carries no risk of non-payment: creating a pay or kya-pay token commits the amount against the buyer agent's wallet, and Skyfire guarantees settlement for a valid token. If you never charge it, that hold releases back to the buyer agent, so nothing is lost on either side. See Payments & Settlement.
3. Charge the token. This step applies only if your seller service accepts pay or kya-pay tokens. Call Charge Token with your seller agent's API key.
   • The token's amount is a maximum, not a fixed charge. Charge what is owed.
   • Partial and repeated charges are allowed, up to the token's value, which suits metered work.
   • A kya token carries no value and cannot be charged.
   • You can charge for up to 24 hours after a token expires, provided you validated it before expiry.
     A request may also arrive with no token, an expired token, or one created for a different seller service.

Next steps

• For creating a seller agent and walking through setup end to end, see Seller Guide.
• For how money moves after a charge, see Payments & Settlement.