Skyfire

Skyfire

Build AI agents that authenticate and charge across external services

Build AI agents that authenticate and charge across external services

Jun 3, 20265 min readBy Skyfire Blog

AI agents need verified identity and payment credentials to execute real transactions across external APIs without authentication failures or blocked checkouts. Skyfire provides an agent trust stack that equips AI agents with verified identity and payment credentials, enabling authenticated access and real transactions. Production-grade agent workflows require separating identity and payment concerns from core agent logic, enforcing strict permission boundaries, and maintaining audit trails for all financial actions. Skyfire's API and SDK let you bind verified credentials to agents, create seller services with identity requirements, and charge tokens as part of agent orchestration loops.

What this tutorial covers

  • •
    Outcome: You will ship a production-grade TypeScript agent workflow that authenticates buyers, creates seller services with identity gates, searches the service directory, and executes charged transactions with full audit trails.
  • •
    Endpoints used: `POST /api/v1/agents/seller-services`, `POST /api/v1/tokens`, `POST /api/v1/tokens/charge`, `GET /api/v1/directory/services`, `GET /api/v1/directory/services/search`
  • •
    SDK methods: `EmbeddedIframeProvider`, `EmbeddedIframe`
  • •
    Language: typescript
  • •
    Auth: API key (X-API-Key header) or Bearer token
  • •
    Estimated implementation time: ~18 minutes

Step 1: Create a seller service with Skyfire identity requirements

Agents need a seller service that enforces buyer identity verification before processing transactions. Skyfire lets you define what identity signals a buyer must present to purchase.

Register seller service endpoint

Response:

json
1{
2  "id": "c8ed8e2c-c32c-4f6d-8b64-144a7b11e8ff",
3  "name": "Enterprise Analytics Platform",
4  "description": "Full-featured enterprise analytics platform with advanced AI-powered insights, custom dashboards, and white-label options.",
5  "tags": [
6    "analytics",
7    "enterprise",
8    "ai",
9    "white-label"
10  ],
11  "type": "API",
12  "price": "0.2",
13  "priceModel": "PAY_PER_USE",
14  "minimumTokenAmount": "0.21",
15  "humanIdentityRequirement": {
16    "identityLevels": [
17      "INDIVIDUAL_LEVEL1"
18    ],
19    "organization": [],
20    "individual": [
21      "birthdate"
22    ]
23  },
24  "termsOfService": {
25    "url": "https://premium-analytics.com/enterprise-terms",
26    "required": true
27  },
28  "seller": {
29    "id": "a8e49eea-ac7b-41f2-aa74-84fb86ad40bc",
30    "name": "Seller 1",
31    "identityLevel": "INDIVIDUAL_LEVEL2"
32  },
33  "openApiSpecUrl": "https://api.premium-analytics.com/v2/openapi.json",
34  "acceptedTokens": [
35    "kya",
36    "pay",
37    "kya-pay"
38  ],
39  "createdAt": "2025-07-18T02:51:54.265Z",
40  "updatedAt": "2025-07-18T02:54:19.767Z",
41  "active": false,
42  "approved": false
43}

Step 2: Mint a token with identity permissions for a buyer agent

Before an agent can transact, Skyfire issues a token binding verified identity and payment permissions. This token proves the agent passed identity checks and has a spending limit.

Create identity-gated token

typescript
1import jwt from 'jsonwebtoken';
2
3const ENTERPRISE_ADMIN_API_KEY = process.env.SKYFIRE_API_KEY;
4const ENV = 'production';
5const BASE_URL = 'https://api.skyfire.xyz';
6
7const buyerAgentId = 'bb713104-c14e-460f-9b7c-f8140fa9bea4';
8const sellerAgentId = '7434230d-0861-46f2-9c2c-a6ee33d07f17';
9const sellerServiceId = 'bc3ff89f-069b-4383-82a9-8cfe53c55fc3';
10
11const kyaPayTokenPayload = {
12  iss: 'kya-pay.example.org',
13  iat: Math.floor(Date.now() / 1000),
14  exp: Math.floor(Date.now() / 1000) + 31622400,
15  jti: 'b9821893-7699-4d24-af06-803a6a16476b',
16  sub: buyerAgentId,
17  aud: sellerAgentId,
18  env: ENV,
19  ssi: sellerServiceId,
20  btg: 'c52e0ef2-e27d-4e95-862e-475a904ae7b2',
21  hid: {
22    email: 'maryjane@buyer.example.com',
23    given_name: 'Mary',
24    family_name: 'Doe'
25  },
26  apd: {
27    id: '4b087db2-b6e5-48b8-8737-1aa8ddf4c4fe',
28    name: 'Acme Shopping Agents',
29    email: 'platform@acme.com',
30    phone_number: '+12345677890',
31    organization_name: 'Acme Shopping Inc.',
32    verifier: 'https://www.verifier.com/',
33    verified: true,
34    verification_id: 'a23c1fe4-a4b7-442d-8bca-3c8fad5ec3a6'
35  },
36  aid: {
37    name: 'Agentic Excellence Я Us',
38    creation_ip: '128.2.42.95',
39    source_ips: ['54.86.50.139-54.86.50.141', '1.1.1.0/24']
40  },
41  spr: '0.01',
42  sps: 'pay_per_use',
43  amt: '15',
44  cur: 'USD',
45  val: '15000000',
46  mnr: 1600,
47  stp: 'card',
48  sti: {
49    type: 'visa_vic',
50    payment_token: '1234567890123456',
51    token_expiration_month: '03',
52    token_expiration_year: '2030',
53    token_security_code: '123'
54  }
55};
56
57const kid = 'YjFdJgFNWj9AkUmtoXILwoeb37PsBuGWVK6_QvFLwJw';
58
59console.log('KYA-Pay Token Payload:', kyaPayTokenPayload);
60console.log('Key ID (kid):', kid);
61console.log('Algorithm: ES256');
62console.log('Type: kya-pay+jwt');
63

Response:

json
1{
2  "kid": "YjFdJgFNWj9AkUmtoXILwoeb37PsBuGWVK6_QvFLwJw",
3  "alg": "ES256",
4  "typ": "kya+jwt",
5  "iss": "https://example.com/issuer",
6  "iat": 1742245254,
7  "exp": 1773867654,
8  "jti": "b9821893-7699-4d24-af06-803a6a16476b",
9  "sub": "bb713104-c14e-460f-9b7c-f8140fa9bea4",
10  "aud": "7434230d-0861-46f2-9c2c-a6ee33d07f17",
11  "env": "production",
12  "ssi": "bc3ff89f-069b-4383-82a9-8cfe53c55fc3",
13  "btg": "4f6cbd39-215c-4516-bf33-cab22862ee60",
14  "hid": {
15    "email": "buyer@buyer.com"
16  },
17  "apd": {
18    "id": "d3306fc0-602b-47e6-9fe2-3d55d028fbd2",
19    "name": "Acme Shopping Agents",
20    "email": "platform@acme.com",
21    "phone_number": "+12345677890",
22    "organization_name": "Acme Shopping Inc.",
23    "verifier": "https://www.verifier.com/",
24    "verified": true,
25    "verification_id": "a23c1fe4-a4b7-442d-8bca-3c8fad5ec3a6"
26  },
27  "aid": {
28    "name": "Acme Agent Extraordinaire",
29    "creation_ip": "54.86.50.139",
30    "source_ips": [
31      "54.86.50.139-54.86.50.141",
32      "1.1.1.0/24",
33      "2001:db8:abcd:0012::/64",
34      "acme.com"
35    ]
36  }
37}

Step 3: Search the Skyfire service directory to discover sellable services

Agent workflows need to discover and filter available services before executing transactions. Skyfire's directory lets agents query by tags, price, and type to find compatible targets.

Query services by tags

Response:

json
1{
2  "data": [
3    {
4      "id": "c8ed8e2c-c32c-4f6d-8b64-144a7b11e8ff",
5      "name": "Enterprise Analytics Platform",
6      "description": "Full-featured enterprise analytics platform with advanced AI-powered insights, custom dashboards, and white-label options.",
7      "tags": [
8        "analytics",
9        "enterprise",
10        "ai",
11        "white-label"
12      ],
13      "type": "API",
14      "price": "0.2",
15      "priceModel": "PAY_PER_USE",
16      "minimumTokenAmount": "0.21",
17      "humanIdentityRequirement": {
18        "identityLevels": [],
19        "organization": [],
20        "individual": []
21      },
22      "termsOfService": {
23        "url": "https://premium-analytics.com/enterprise-terms",
24        "required": true
25      },
26      "seller": {
27        "id": "a8e49eea-ac7b-41f2-aa74-84fb86ad40bc",
28        "name": "Seller 1"
29      },
30      "openApiSpecUrl": "https://api.premium-analytics.com/v2/openapi.json",
31      "acceptedTokens": [
32        "kya",
33        "pay",
34        "kya-pay"
35      ],
36      "createdAt": "2025-07-18T02:51:54.265Z",
37      "updatedAt": "2025-07-18T02:54:19.767Z",
38      "active": false,
39      "approved": false
40    }
41  ]
42}

Step 4: Charge the token as a seller agent when transaction completes

Once an agent orchestrates a transaction and the buyer has approved it, Skyfire's charge endpoint atomically debits the token and records the transaction for audit trails and compliance.

Execute token charge

typescript
1const ENTERPRISE_ADMIN_API_KEY = 'your-enterprise-admin-key'
2const ENV = 'production'
3const BASE_URLS = {
4  sandbox: 'https://api-sandbox.skyfire.xyz',
5  production: 'https://api.skyfire.xyz'
6}
7const baseUrl = BASE_URLS[ENV]
8
9async function chargeTokenOnTransactionComplete(
10  userId: string,
11  kya_pay_token: string,
12  sellerId: string
13) {
14  const chargeUrl = `${baseUrl}/api/v1/transactions/charge`
15  const res = await fetch(chargeUrl, {
16    method: 'POST',
17    body: JSON.stringify({
18      userId: userId,
19      token: kya_pay_token,
20      sellerId: sellerId,
21    }),
22    headers: {
23      'Content-Type': 'application/json',
24      'skyfire-api-key': ENTERPRISE_ADMIN_API_KEY,
25    },
26  })
27  const chargeResult = await res.json()
28  return chargeResult
29}

Response:

json
1{
2  "iss": "https://example.net/pay_token_issuer",
3  "iat": 1742245254,
4  "exp": 1773867654,
5  "jti": "b9821893-7699-4d24-af06-803a6a16476b",
6  "sub": "8b810549-7443-494f-b4ad-5bc65871e32b",
7  "aud": "37888095-2721-48d9-a2df-bfe4075f223a",
8  "env": "sandbox",
9  "ssi": "274efc47-024e-466f-b278-152d2ee73955",
10  "btg": "16c135ce-a99a-453d-a7b5-4958fd91de5f",
11  "spr": "0.01",
12  "sps": "pay_per_use",
13  "amt": "15",
14  "cur": "USD",
15  "val": "15000000",
16  "mnr": 1600,
17  "stp": "card",
18  "sti": {
19    "type": "visa_vic",
20    "payment_token": "1234567890123456",
21    "token_expiration_month": "03",
22    "token_expiration_year": "2030",
23    "token_security_code": "123",
24    "verifier": "https://verifier.example.info",
25    "verified": true,
26    "verification_id": "3a6e1b76-8f78-4c24-b1bd-dc78a8cc3711"
27  }
28}

Step 5: Embed Skyfire's wallet UI for agent wallet funding

Agent deployments often need to replenish tokens without exposing credentials. Skyfire's embedded iframe lets agents or administrators securely fund wallets in your application UI.

EmbeddedIframe wallet funding

typescript
1import { EmbeddedIframeProvider, EmbeddedIframe, EmbeddedIframeOptions } from '@skyfire/credits-wallet-embed-sdk'
2
3const ENTERPRISE_ADMIN_API_KEY = process.env.SKYFIRE_API_KEY
4const ENV = process.env.SKYFIRE_ENV || 'sandbox'
5
6const BASE_URLS = {
7  sandbox: 'https://api-sandbox.skyfire.xyz',
8  production: 'https://api.skyfire.xyz'
9}
10
11async function functionToGetSkyfireUserSession(userId: string) {
12  const baseUrl = BASE_URLS[ENV]
13  const sessionTokenUrl = `${baseUrl}/api/v1/visa/skyfire-session-token`
14
15  const res = await fetch(sessionTokenUrl, {
16    method: 'POST',
17    body: JSON.stringify({
18      userId: userId,
19    }),
20    headers: {
21      'Content-Type': 'application/json',
22      'skyfire-api-key': ENTERPRISE_ADMIN_API_KEY,
23    },
24  })
25
26  return await res.json()
27}
28
29export default function WalletFundingApp() {
30  const options: EmbeddedIframeOptions = {
31    fetchClientSecret: () => functionToGetSkyfireUserSession('agent-user-id'),
32    onEvent: async (type: unknown, data: unknown) => {
33      console.log('Wallet funding event:', type, data)
34    },
35    environment: ENV,
36    buttonText: 'Fund Agent Wallet',
37  }
38
39  return (
40    <EmbeddedIframeProvider options={options}>
41      <EmbeddedIframe />
42    </EmbeddedIframeProvider>
43  )
44}

The iframe renders Skyfire's secure wallet funding UI inside your application, allowing agents to deposit funds without exposing payment credentials to your backend.

Common pitfalls when using Skyfire

  • •
    Confusing token permissions with transaction execution. A token with identity permissions proves the agent passed KYC, but it does not auto-execute transactions. The agent's orchestration loop must still call the charge endpoint explicitly and log the decision (approval or denial) outside the model prompt for compliance.
  • •
    Forgetting to validate service identity requirements before charging. Always fetch the seller service definition and confirm the buyer's token satisfies all identity gates (minReputation, requiresKyc, allowedCountries) before calling /api/v1/tokens/charge, to prevent rejected transactions and poor user experience.
  • •
    No audit trail separation between agent decision and financial action. Record the agent's charge request, the actual charge response from Skyfire, and the observation fed back to the agent in separate log tables, so auditors can trace who authorized what and Skyfire's audit proves the financial action was atomic.
  • •
    Ignoring token expiration and spending limits in production workflows. Always check the token's usableUntil date and remaining balance before routing a transaction to the charge endpoint. Expired or over-limit tokens will fail mid-transaction; implement pre-flight validation to reject requests gracefully.

Your agent is now equipped with verified identity and payment credentials. Ready to deploy this at scale? Get started with Skyfire and ship production-grade workflows today.

Documentation references

The code examples in this tutorial are grounded in the following docs pages:

Ready to power your agents with real credentials?

Join teams using Skyfire’s trust stack to enable secure transactions and authenticated API access for AI agents across the internet.

Read More Blog Posts

Jun 3, 2026•6 min read

Cisco Cloud Control: Design Infra for AI Agents Now

Cisco has launched Security Cloud Control, a unified, cloud-native management platform that centralizes firewalls, multicloud defense, secure access, and securi

Cisco Security Cloud ControlAI Agents Infrastructure Automation
SkyfireSkyfire

Trusted infrastructure for scalable AI agent deployments.

© 2026 Skyfire. All rights reserved.