--- updatedAt: 2026-09-29T18:33:48.000Z agentTools: projectIndex: https://docs.skyfire.xyz/llms.txt --- # Create Token Create a `kya`, `pay`, or `kya-pay` token as a buyer agent. ## Choose a Seller Type Tokens can be created for either an **onboarded seller** or an **external seller**. ### 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 * Default token expiration: **24 hours** (or 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 * Supports only `kya` tokens * Default token expiration: **5 minutes** > Currently, external seller token creation is available only to Skyfire organizations. Standard Skyfire Buyer Agents cannot create tokens for external sellers. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "skyfire-agent-and-token-apis", "version": "1.0" }, "servers": [ { "url": "https://api.skyfire.xyz" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "skyfire-api-key", "in": "header" } } }, "security": [ { "sec0": [] } ], "paths": { "/api/v1/tokens": { "post": { "summary": "Create Token", "description": "Create a `kya`, `pay`, or `kya-pay` token as a buyer agent.", "operationId": "create-token", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "One of `kya`, `pay`, or `kya-pay`. The created token will contain JWT header `typ` set to `+jwt`." }, "buyerTag": { "type": "string", "description": "Buyer’s internal identifier for the token. e.g. \"research-agent-xyz\"" }, "tokenAmount": { "type": "string", "description": "The amount of funds in currency units allocated to the token. Determines the maximum amount the seller can charge. Must include if this is a `pay`or `kya-pay` token. For successful token creation, this value must be:\n- Greater than 0\n- Less than or equal to the buyer agent wallet balance\n- Greater than or equal to the seller service minimum token amount (if applicable)\n\nIf these conditions are not met, the token creation request will fail." }, "sellerServiceId": { "type": "string", "description": "ID of an onboarded seller service. Obtain this from the Skyfire Directory. Required when creating a token for an onboarded seller." }, "sellerDomainOrUrl": { "type": "string", "description": "Domain name or full URL of an external seller. The buyer agent must belong to an organization and authenticate using an Organization Buyer API Key. Required when creating a token for an external seller." }, "expiresAt": { "type": "integer", "description": "Unix timestamp (seconds) representing when the token expires. Provide an absolute epoch time, not a relative duration. If omitted, defaults to the maximum allowed lifetimes:\n* 24 hours from now when using `sellerServiceId`\n* 5 minutes from now when using `sellerDomainOrUrl`\n\nMust be between 10s and the maximum allowed lifetime for the selected target type.", "format": "int64" }, "identityPermissions": { "type": "array", "description": "Default: empty array. Can be specified if this is a `kya` or `kya-pay` token. Additional identity fields to include in the token. See https://docs.skyfire.xyz/reference/identity-fields for more info.", "items": { "type": "string" } } } }, "examples": { "Create a token to an Onboarded Seller": { "summary": "Create a token to an Onboarded Seller", "value": { "type": "kya-pay", "buyerTag": "efd8a6ee-c7b6-4d26-9e5c-3b5e9c180df6", "tokenAmount": "0.005", "sellerServiceId": "350d433d-6ed4-4482-bcfc-14b7da807f9b", "expiresAt": 1752919200 } }, "Create a token to an External Seller": { "summary": "Create a token to an External Seller", "value": { "type": "kya", "buyerTag": "efd8a6ee-c7b6-4d26-9e5c-3b5e9c180df6", "sellerDomainOrUrl": "https://kyapaynews.com", "expiresAt": 1763769321 } } } } }, "required": true }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "examples": { "Ok": { "summary": "Ok", "value": { "token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAiLCJ0eXAiOiJreWErcGF5K0pXVCJ9.eyJlbnYiOiJxYSIsImJ0ZyI6ImVmZDhhNmVlLWM3YjYtNGQyNi05ZTVjLTNiNWU5YzE4MGRmNiIsInNzaSI6IjM1MGQ0MzNkLTZlZDQtNDQ4Mi1iY2ZjLTE0YjdkYTgwN2Y5YiIsImJpZCI6eyJuYW1lRmlyc3QiOiJBTEVYQU5ERVIgSiIsIm5hbWVNaWRkbGUiOiJudWxsIiwibmFtZUxhc3QiOiJTQU1QTEUiLCJiaXJ0aGRhdGUiOiIxOTc3LTA3LTE3IiwicGhvbmVOdW1iZXIiOiIrMTgxNjY2ODMwMzUiLCJzZWxlY3RlZENvdW50cnlDb2RlIjoiVVMiLCJzZWxlY3RlZElkQ2xhc3MiOiJkbCIsImlzc3VlRGF0ZSI6IjIwMjQtMDctMTgiLCJpc3N1aW5nQXV0aG9yaXR5IjoiQ0EiLCJleHBpcmF0aW9uRGF0ZSI6IjIwMzAtMDctMTgiLCJhZGRyZXNzU3RyZWV0MSI6IjYwMCBDQUxJRk9STklBIFNUUkVFVCIsImFkZHJlc3NTdHJlZXQyIjoibnVsbCIsImFkZHJlc3NDaXR5IjoiU0FOIEZSQU5DSVNDTyIsImFkZHJlc3NTdWJkaXZpc2lvbiI6IkNBIiwiYWRkcmVzc1Bvc3RhbENvZGUiOiI5NDEwOSIsImFkZHJlc3NDb3VudHJ5Q29kZSI6IlVTIiwic2t5ZmlyZUVtYWlsIjoiYW5raXRAc2t5ZmlyZS54eXoifSwiYWlkIjpudWxsLCJ2YWx1ZSI6IjUwMDAiLCJhbW91bnQiOiIwLjAwNSIsInNwcyI6IlBBWV9QRVJfVVNFIiwic3ByIjoiMC4wMDAwMDEiLCJtbnIiOjUwMDAsImN1ciI6IlVTRCIsImlhdCI6MTc1Mjg0MzM1MCwiaXNzIjoiaHR0cHM6Ly9hcHAtcWEuc2t5ZmlyZS54eXoiLCJqdGkiOiIxMThhMTUyNi0xMWVhLTRjNzctODNiMS0yODdlN2MwMWJmZGEiLCJhdWQiOiI5ODc1NWExNS1iY2JiLTRlN2MtYTRhYy0wYWUyMWI5Y2U1YzciLCJzdWIiOiI0MjVhMzk0Yi01ZWE1LTRmNjUtOTU2NS0zNjBlYTg1NDU2NWEiLCJleHAiOjE3NTI5MTkyMDB9.1MWp5Fj4RTUs-ckOfyXDWzPy1pNl951ZvyGzVdLznUrjRPBKwbIky4OYlo3JMyFu9glaTCrjNn-PnNpwGLO8pQ" } } }, "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The signed JWT for the token." } }, "required": [ "token" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "code": "NOT_AUTHORIZED", "message": "Subscription Required" } } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "NOT_AUTHORIZED" }, "message": { "type": "string", "example": "Subscription Required" } } } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "HTTP status code." }, "message": { "type": "string", "description": "Human-readable error message." }, "payment_details": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why payment is required." }, "network": { "type": "string", "description": "Payment network." }, "payment_type": { "type": "string", "description": "Payment type." } } } } } } }, "examples": { "Payment Required": { "summary": "Payment Required", "value": { "error": { "code": 402, "message": "Payment Required", "payment_details": { "reason": "Insufficient balance to access this resource.", "network": "skyfire", "payment_type": "per_usage" } } } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "examples": { "Unprocessable Entity": { "summary": "Unprocessable Entity", "value": { "code": "VALIDATION_ERROR", "message": "Validation Error", "details": { "paymentInfo.type": { "message": "'type' is required" } } } } }, "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "Validation Error" }, "details": { "type": "object", "properties": { "paymentInfo.type": { "type": "object", "properties": { "message": { "type": "string", "example": "'type' is required" } } } } } } } } } } }, "x-readme": { "code-samples": [ { "code": "curl -i -X POST 'https://api.skyfire.xyz/api/v1/tokens' \\\n -H 'skyfire-api-key: a27829f9-5db7-4f18-938d-5d323278f773' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"type\": \"kya-pay\",\n \"buyerTag\": \"research-agent-xyz\",\n \"tokenAmount\": \"0.005\",\n \"sellerServiceId\": \"350d433d-6ed4-4482-bcfc-14b7da807f9b\",\n \"expiresAt\": 1752919200\n}'", "language": "shell", "name": "cURL" }, { "code": "const res = await fetch(\n 'https://api.skyfire.xyz/api/v1/tokens',\n {\n method: 'POST',\n headers: {\n 'skyfire-api-key': 'a27829f9-5db7-4f18-938d-5d323278f773',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n type: 'kya-pay',\n buyerTag: 'research-agent-xyz',\n tokenAmount: '0.005',\n sellerServiceId: '350d433d-6ed4-4482-bcfc-14b7da807f9b',\n expiresAt: 1752919200\n })\n }\n);\nconsole.log(await res.json());", "language": "node", "name": "" }, { "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"api.skyfire.xyz\")\nheaders = {\n 'skyfire-api-key': 'a27829f9-5db7-4f18-938d-5d323278f773',\n 'Content-Type': 'application/json'\n}\npayload = json.dumps({\n \"type\": \"kya-pay\",\n \"buyerTag\": \"research-agent-xyz\",\n \"tokenAmount\": \"0.005\",\n \"sellerServiceId\": \"350d433d-6ed4-4482-bcfc-14b7da807f9b\",\n \"expiresAt\": 1752919200\n})\nconn.request(\"POST\", \"/api/v1/tokens\", payload, headers)\nres = conn.getresponse()\nprint(res.read().decode(\"utf-8\"))", "language": "python", "name": "" } ], "samples-languages": [ "shell", "node", "python" ] } } } }, "x-readme": { "headers": [ { "key": "skyfire-api-key", "value": "" } ], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```