Skyfire Developer Documentation

This guide provides technical instructions for using the Skyfire platform as both a buyer and seller.

Overview

Skyfire enables programmatic interaction between buyers and sellers through a token based payment and identity protocol. Each user manages agent accounts (buyer or seller). Buyers can interact with seller's website, MCP servers, APIs and services by leveraging Skyfire's identity (kya) and payment (pay) tokens.

Users

A User is the top-level entity on the Skyfire platform. Users typically represent a person or business and are responsible for managing their agent accounts.

A user may create one or more agent accounts to act as a buyer or seller.
Each agent can only represent one role: either a buyer or a seller.
A user's verified identity can be used by their agents for sign up, authentication and service access.

Agent accounts

Agent accounts are the operational entities used to access the Skyfire APIs. Each agent is tied to a specific user and serves a distinct role:

Agents can be either buyers or sellers, but not both.
Each user is allowed:
- One buyer agent account (created by default at signup).
- One optional seller agent account, created via the Skyfire Dashboard.
Agent accounts are accessed programmatically using unique API keys.
Each agent may have one or more API keys for secure access.

Buyer Agent account

The buyer agent acts on behalf of the user to discover and purchase services or tools from sellers.

Can create accounts at seller services and subscribe or pay for them.
Has an associated wallet funded by the user to enable transactions.
Can generate:
- kya tokens for identity.
- pay tokens for payment.
- Combined kya+pay tokens via the Skyfire API.
When interacting with a seller, the buyer includes these tokens in requests (per the seller's API specification e.g. HTTP header or request body).

Seller Agent Account

The seller agent enables users to offer services, tools, or APIs for consumption by buyers.

Must be explicitly created via the Skyfire Dashboard.
Can register Seller Services for discovery and token-based access.
Can define identity and payment requirements for incoming buyer requests.
Verifies tokens via standard JWKS mechanisms to:
- Authenticate the buyer (kya).
- Charge the buyer (pay or kya+pay).
Sellers receive payments via Skyfire's settlement system once services are delivered.

Seller Services

Seller services are the products, tools, or APIs made available by seller agents to buyers.

A seller can define multiple seller services under one seller agent.
Services may include:
- Remote/local MCP servers
- APIs
- Websites
Each Seller Service specifies:
- Pricing
- Identity requirements
  - If a Seller Service does not specify any identity requirements, then any buyer can create tokens for it
    - In this case, the buyer principal's email address will be included in the bid claim
  - If a Seller Service specifies identity requirements, then only buyers that satisfy those identity requirements can create tokens for it
    - If a Seller specifies only business identity requirements, then only buyers that have verified their business identity can create tokens
      - Buyers that have NOT verified identity at all OR have verified individual identity CANNOT create tokens
    - If a Seller specifies only individual identity requirements, then only buyers that have verified their individual identity can create tokens
      - Buyers that have NOT verified identity at all OR have verified business identity CANNOT create tokens
    - If a Seller specifies both individual and business identity requirements, then only buyers that have verified either their individual identity or their business identity can create tokens
      - Buyers that have NOT verified identity at all CANNOT create tokens
- Token format and expected delivery method (e.g. HTTP header).
Services can be:
- Paid, using pay or kya+pay tokens.
- Free, requiring only identity (kya) tokens.

Wallets

Each agent account comes with an associated wallet, managed by Skyfire.

Buyers fund their wallets to purchase services and tools.
Sellers receive funds in their wallets after successfully charging buyer tokens and delivering the service.
Skyfire handles settlement and transfer of funds between wallets after a successful transaction.