Home
API Reference

Create Token

post
https://api.skyfire.xyz/api/v1/tokens

Create a kya, pay, or kya-pay token as a buyer agent. Only buyer agents can create tokens; a seller agent key is rejected.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Choose a Seller Type

Tokens can be created for either an onboarded seller or an external seller. Provide exactly one of sellerServiceId or sellerDomainOrUrl. Sending both, or
neither, is rejected.

Onboarded Seller (sellerServiceId)

Use this when the seller is onboarded to Skyfire and has a Seller Service listed in the Skyfire Directory.

  • Provide sellerServiceId
  • Uses your standard Skyfire Buyer Agent API key
  • Supports kya, pay, and kya-pay tokens, subject to the token types the seller service accepts
  • pay and kya-pay tokens are funded from your stablecoin wallet
  • tokenAmount accepts up to six decimal places and must meet the seller's minimum
  • Default token expiration: 24 hours (or a shorter maximum configured by the seller)

External Seller (sellerDomainOrUrl)

Use this when accessing a website, webpage, or API that is not onboarded to Skyfire.

  • Provide sellerDomainOrUrl
  • Available only to buyer agents that belong to a Skyfire Organization
  • kya tokens need nothing else
  • pay and kya-pay tokens must be funded from a Visa or Mastercard wallet: pass the card wallet's ID as accountId and the card details in additionalInfo. Stablecoin-funded payments to external sellers are not supported.
  • Default token expiration: 5 minutes, or a maximum configured for that domain

External seller token creation is available only to Skyfire organizations. Standard Skyfire Buyer Agents cannot create tokens for external sellers.

Agent group instances

A buyer agent that is an instance of an agent group creates tokens the same way, with its own API key. Its tokens carry the group's name in aid.name and the agent's own ID in aid.id. While the group is deactivated, the request is refused with 400 and the message Agent group is deactivated; tokens cannot be issued until it is reactivated.

Body Params
string
enum
required

One of kya, pay, or kya-pay. The created token will contain JWT header typ set to <type>+jwt. Onboarded sellers only accept the token types listed on their service.

Allowed:
string

Buyer’s internal identifier for the token. e.g. "research-agent-xyz". Max 128 characters.

string

Amount of funds, in USD, allocated to the token. This is the maximum the seller can charge. Required for pay and kya-pay; must be omitted for kya. Plain decimal string: no sign, no exponent. Onboarded sellers accept up to six decimal places and enforce their own minimum. External sellers accept at most two decimal places. Must be greater than zero and no more than the wallet balance.

string

ID of an onboarded seller service. Use this or sellerDomainOrUrl, never both. The service must be active and approved, and must accept the requested token type.

string

Domain name or full URL of an external seller, with or without a scheme. Use this or sellerServiceId, never both. Requires an Organization Buyer API key.

int64

Unix time in seconds at which the token expires. Provide an absolute epoch time, not a duration. Omit to get the maximum lifetime:

  • 24 hours for an onboarded seller
  • 5 minutes for an external seller, or a shorter per-seller maximum where configured.

A supplied value is clamped into the allowed window rather than rejected: anything earlier than 10 seconds from now becomes 10 seconds from now, anything later than the maximum becomes the maximum.

identityPermissions
array of strings

Additional identity fields to include in the token. Allowed on kya and kya-pay; a pay request that includes it is rejected. Defaults to none. See https://docs.skyfire.xyz/reference/identity-fields.

identityPermissions
string

ID of the agent wallet that funds the token. Defaults to the agent's active wallet on the default stablecoin network. Required, and must be an active Visa or Mastercard wallet, when additionalInfo is provided.

additionalInfo
object

Card payment details. Required, together with accountId, to fund a pay or kya-pay token to an external seller from a Visa or Mastercard wallet. Omit for stablecoin-funded tokens and for kya tokens.

Responses

Updated 11 days ago

Did this page help you?
Language
Credentials
Header
LoadingLoading…
Response
Choose an example:
application/json

Updated 11 days ago

Did this page help you?