Build on Gao

Everything you build on Gao Internet goes through one interface: @gao/system-sdk. The SDK routes your calls through the capability engine to the correct layer — you never call layers directly.

The Golden Rule#

Your dApp ↓ @gao/system-sdk ← always use this ↓ Capability Token Engine ↓ Target Layer (Identity / Settlement / Intelligence / DePIN / ...)

Never call Gao layers directly. This ensures capability validation, policy enforcement, and audit logging happen on every action.

Common Capabilities

Capability

Action

intelligence:agent:run

Run an AI agent

intelligence:agent:deploy

Create a new agent

intelligence:sandbox:execute

Execute code in sandbox

settlement:intent:create

Create a payment intent

identity:record:resolve

Resolve a .gao domain

infrastructure:storage:write

Upload to GaoStorage

infrastructure:compute:allocate

Submit a compute job

transport:message:send

Send a Meshii message

developer:connector:gmail:send

Send via Gmail connector

developer:connector:slack:send

Send via Slack connector

Build Patterns#

Pattern A — AI Agent App

// Stream agent output token by token
for await (const chunk of sdk.intelligence.runAgentStream(agentId, userIntent)) {
  if (chunk.type === 'text')     appendToUI(chunk.delta)
  if (chunk.type === 'tool_use') showToolCard(chunk.tool)
  if (chunk.type === 'artifact') showResultCard(chunk)
  if (chunk.type === 'done')     finalizeSession()
}

Best for: booking apps, support bots, data analysis, Seal merchants.

Pattern B — Payment App

const intent = await sdk.settlement.createIntent({
  amount: '50.00',
  currency: 'USDC',
  recipient: 'merchant.gao',
  idempotency_key: orderId,    // always unique — prevents duplicate charges
  capability: cap.token,
})

// Always validate receipt before fulfilling order
const valid = await sdk.settlement.validateReceipt(intent.receipt)
if (!valid) throw new Error('Invalid receipt — do not fulfill')

// Watch for on-chain finality
const finality = await sdk.settlement.watchFinality(intent.intent_id)
if (finality.status === 'confirmed') fulfillOrder()

Best for: checkout, invoices, subscriptions, DAO treasury.

Pattern C — Messaging App

// Send
await sdk.transport.message.send({
  to: 'alice.gao',
  content: 'Your appointment is confirmed for tomorrow at 3pm',
  type: 'notification',
})

// Receive (subscribe)
const unsub = sdk.transport.message.subscribe((msg) => {
  displayMessage(msg.decrypted.content)
})
// call unsub() to stop listening

// Agent sends as bot identity
await sdk.transport.message.sendAsAgent(agentId, customerTag, 'Hi! How can I help?')

Best for: notifications, chat apps, agent-to-user communication.

Pattern D — Storage App

// Upload (encrypted by default)
const receipt = await sdk.infrastructure.storage.upload(fileBuffer, {
  encrypted: true,
  redundancy: 3,
  content_type: 'application/pdf',
})
console.log(receipt.cid) // content-addressed ID

// Download
const data = await sdk.infrastructure.storage.download(receipt.cid)

// Delete
await sdk.infrastructure.storage.delete(receipt.cid)

Best for: document vaults, encrypted backups, content distribution.

Pattern E — Identity-Verified App

// Resolve domain
const record = await sdk.identity.resolve('alice.gao')

// Verify domain ownership
const owns = await sdk.identity.isOwner('alice.gao', walletAddress)

// Challenge-response login
const valid = await sdk.identity.verifySignature('alice.gao', challenge, signature)
if (valid) grantAccess()

Best for: domain-gated content, DAO membership, enterprise access control.

Pattern F — Scheduled Automation

// Daily cron job
const job = await sdk.intelligence.scheduler.create({
  agent_id: 'report-agent',
  owner_domain: 'myapp.gao',
  trigger_type: 'cron',
  trigger_config: {
    expression: '0 9 * * *',     // every day at 9am
    timezone: 'America/Chicago',
  },
  retry_policy: { max_retries: 3, backoff: 'exponential' },
})

// Webhook trigger
const job = await sdk.intelligence.scheduler.create({
  trigger_type: 'webhook',
  trigger_config: { secret: crypto.randomUUID() },
})
// POST to your webhook URL → triggers agent automatically

Best for: daily reports, appointment reminders, monitoring, pipelines.

Receipt Model#

Every state-changing operation returns an immutable, signed receipt.

interface Receipt {
  receipt_id:    string
  domain:        string
  action:        string
  status:        'pending' | 'confirmed' | 'failed'
  payload:       unknown
  signature:     string   // domain-signed
  timestamp:     string   // ISO8601
  finality_hash?: string  // after on-chain confirmation
  immutable:     true
}

Always validate receipts before proceeding. Never modify them.

Gao-Native Services First#

Need

Use

Instead of

Messaging

sdk.transport — Meshii

Twilio, Firebase

Payment

sdk.settlement — Payii

Stripe, PayPal

Storage

sdk.infrastructure — GaoStorage

AWS S3, IPFS

Identity

sdk.identity — Gao Domain

Auth0, Okta

sdk.intelligence — GAR

OpenAI Assistants

Gao-native services share the same domain identity, audit trail, and capability system — consistent behavior across your entire stack.

Error Handling#

import { GaoError } from '@gao/system-sdk'

try {
  await sdk.intelligence.runAgent(agentId, intent)
} catch (err) {
  if (err instanceof GaoError) {
    switch (err.code) {
      case 'GAO-4001': // capability expired → re-request
        const newCap = await sdk.developer.capability.request(...)
        break
      case 'GAO-4002': // budget exceeded
        notifyUser('Budget limit reached')
        break
      case 'GAO-4003': // route unavailable → retry
        await retry(3, exponentialBackoff)
        break
      case 'GAO-4005': // invalid receipt → abort
        throw new Error('Receipt invalid — do not proceed')
      case 'GAO-4006': // replay detected → new idempotency key
        idempotencyKey = crypto.randomUUID()
        break
    }
  }
}

Code

Meaning

Action

GAO-4001

Capability expired

Re-request capability

GAO-4002

Budget exceeded

Check Studio billing

GAO-4003

Route unavailable

Retry with backoff

GAO-4004

Finality timeout

Check receipt status

GAO-4005

Receipt invalid

Abort — do not retry

GAO-4006

Replay detected

New idempotency_key

GAO-4007

Policy mismatch

Reload policy

Non-Custodial Rules#

The SDK never:

Stores private keys
Pools or holds funds
Executes unsigned transactions
Modifies receipts after generation

All write actions require capability validation + explicit authorization.

Production Checklist#

All capability tokens have appropriate TTL
All payment flows validate receipts before fulfillment
All state-changing ops have unique idempotency_key
All GAO-4xxx error codes handled
TypeScript strict mode enabled — no any
No secrets or private keys in client-side code
Passkey auth tested on real devices (iOS + Android)
Audit events visible in Studio → Traces

Next Steps#

SDK Guide — complete method reference for all 8 modules
API Reference — REST endpoints
Example Apps — full working code

Never call Gao layers directly. This ensures capability validation, policy enforcement, and audit logging happen on every action.

-----

## Layer Map

|Module              |Layer            |What It Does                             |
|--------------------|-----------------|-----------------------------------------|
|`sdk.workspace`     |Operations (L1)  |Manage agents, policies, audit log       |
|`sdk.browser`       |Gateway (L2)     |Domain resolution helpers, x402 proofs   |
|`sdk.developer`     |Developer (L3)   |Capability tokens, connector registry    |
|`sdk.settlement`    |Settlement (L4)  |Payments, receipts, budget management    |
|`sdk.identity`      |Identity (L5)    |Resolve `.gao` domains, verify signatures|
|`sdk.transport`     |Transport (L6)   |Messaging via Meshii Protocol            |
|`sdk.infrastructure`|DePIN (L7)       |Encrypted storage, compute jobs          |
|`sdk.intelligence`  |Intelligence (L8)|AI agents, tools, scheduler              |

-----

## Capability Tokens

Every cross-layer action requires a capability token — time-bound and domain-scoped.

```typescript
const cap = await sdk.developer.capability.request(
  'intelligence:agent:run',  // capability format: `<layer>`:`<resource>`:`<action>`
  'myapp.gao',               // domain scope
  3600                       // TTL in seconds
)
// SDK auto-attaches to subsequent calls
// Re-request when GAO-4001 (expired) error occurs

Common Capabilities

Capability

Action

intelligence:agent:run

Run an AI agent

intelligence:agent:deploy

Create a new agent

intelligence:sandbox:execute

Execute code in sandbox

settlement:intent:create

Create a payment intent

identity:record:resolve

Resolve a .gao domain

infrastructure:storage:write

Upload to GaoStorage

infrastructure:compute:allocate

Submit a compute job

transport:message:send

Send a Meshii message

developer:connector:gmail:send

Send via Gmail connector

developer:connector:slack:send

Send via Slack connector

Build Patterns#

Pattern A — AI Agent App

// Stream agent output token by token
for await (const chunk of sdk.intelligence.runAgentStream(agentId, userIntent)) {
  if (chunk.type === 'text')     appendToUI(chunk.delta)
  if (chunk.type === 'tool_use') showToolCard(chunk.tool)
  if (chunk.type === 'artifact') showResultCard(chunk)
  if (chunk.type === 'done')     finalizeSession()
}

Best for: booking apps, support bots, data analysis, Seal merchants.

Pattern B — Payment App

const intent = await sdk.settlement.createIntent({
  amount: '50.00',
  currency: 'USDC',
  recipient: 'merchant.gao',
  idempotency_key: orderId,    // always unique — prevents duplicate charges
  capability: cap.token,
})

// Always validate receipt before fulfilling order
const valid = await sdk.settlement.validateReceipt(intent.receipt)
if (!valid) throw new Error('Invalid receipt — do not fulfill')

// Watch for on-chain finality
const finality = await sdk.settlement.watchFinality(intent.intent_id)
if (finality.status === 'confirmed') fulfillOrder()

Best for: checkout, invoices, subscriptions, DAO treasury.

Pattern C — Messaging App

// Send
await sdk.transport.message.send({
  to: 'alice.gao',
  content: 'Your appointment is confirmed for tomorrow at 3pm',
  type: 'notification',
})

// Receive (subscribe)
const unsub = sdk.transport.message.subscribe((msg) => {
  displayMessage(msg.decrypted.content)
})
// call unsub() to stop listening

// Agent sends as bot identity
await sdk.transport.message.sendAsAgent(agentId, customerTag, 'Hi! How can I help?')

Best for: notifications, chat apps, agent-to-user communication.

Pattern D — Storage App

// Upload (encrypted by default)
const receipt = await sdk.infrastructure.storage.upload(fileBuffer, {
  encrypted: true,
  redundancy: 3,
  content_type: 'application/pdf',
})
console.log(receipt.cid) // content-addressed ID

// Download
const data = await sdk.infrastructure.storage.download(receipt.cid)

// Delete
await sdk.infrastructure.storage.delete(receipt.cid)

Best for: document vaults, encrypted backups, content distribution.

Pattern E — Identity-Verified App

// Resolve domain
const record = await sdk.identity.resolve('alice.gao')

// Verify domain ownership
const owns = await sdk.identity.isOwner('alice.gao', walletAddress)

// Challenge-response login
const valid = await sdk.identity.verifySignature('alice.gao', challenge, signature)
if (valid) grantAccess()

Best for: domain-gated content, DAO membership, enterprise access control.

Pattern F — Scheduled Automation

// Daily cron job
const job = await sdk.intelligence.scheduler.create({
  agent_id: 'report-agent',
  owner_domain: 'myapp.gao',
  trigger_type: 'cron',
  trigger_config: {
    expression: '0 9 * * *',     // every day at 9am
    timezone: 'America/Chicago',
  },
  retry_policy: { max_retries: 3, backoff: 'exponential' },
})

// Webhook trigger
const job = await sdk.intelligence.scheduler.create({
  trigger_type: 'webhook',
  trigger_config: { secret: crypto.randomUUID() },
})
// POST to your webhook URL → triggers agent automatically

Best for: daily reports, appointment reminders, monitoring, pipelines.

Receipt Model#

Every state-changing operation returns an immutable, signed receipt.

interface Receipt {
  receipt_id:    string
  domain:        string
  action:        string
  status:        'pending' | 'confirmed' | 'failed'
  payload:       unknown
  signature:     string   // domain-signed
  timestamp:     string   // ISO8601
  finality_hash?: string  // after on-chain confirmation
  immutable:     true
}

Always validate receipts before proceeding. Never modify them.

Gao-Native Services First#

Need

Use

Instead of

Messaging

sdk.transport — Meshii

Twilio, Firebase

Payment

sdk.settlement — Payii

Stripe, PayPal

Storage

sdk.infrastructure — GaoStorage

AWS S3, IPFS

Identity

sdk.identity — Gao Domain

Auth0, Okta

sdk.intelligence — GAR

OpenAI Assistants

Gao-native services share the same domain identity, audit trail, and capability system — consistent behavior across your entire stack.

Error Handling#

import { GaoError } from '@gao/system-sdk'

try {
  await sdk.intelligence.runAgent(agentId, intent)
} catch (err) {
  if (err instanceof GaoError) {
    switch (err.code) {
      case 'GAO-4001': // capability expired → re-request
        const newCap = await sdk.developer.capability.request(...)
        break
      case 'GAO-4002': // budget exceeded
        notifyUser('Budget limit reached')
        break
      case 'GAO-4003': // route unavailable → retry
        await retry(3, exponentialBackoff)
        break
      case 'GAO-4005': // invalid receipt → abort
        throw new Error('Receipt invalid — do not proceed')
      case 'GAO-4006': // replay detected → new idempotency key
        idempotencyKey = crypto.randomUUID()
        break
    }
  }
}

Code

Meaning

Action

GAO-4001

Capability expired

Re-request capability

GAO-4002

Budget exceeded

Check Studio billing

GAO-4003

Route unavailable

Retry with backoff

GAO-4004

Finality timeout

Check receipt status

GAO-4005

Receipt invalid

Abort — do not retry

GAO-4006

Replay detected

New idempotency_key

GAO-4007

Policy mismatch

Reload policy

Non-Custodial Rules#

The SDK never:

Stores private keys
Pools or holds funds
Executes unsigned transactions
Modifies receipts after generation

All write actions require capability validation + explicit authorization.

Production Checklist#

All capability tokens have appropriate TTL
All payment flows validate receipts before fulfillment
All state-changing ops have unique idempotency_key
All GAO-4xxx error codes handled
TypeScript strict mode enabled — no any
No secrets or private keys in client-side code
Passkey auth tested on real devices (iOS + Android)
Audit events visible in Studio → Traces

Next Steps#

SDK Guide — complete method reference for all 8 modules
API Reference — REST endpoints
Example Apps — full working code