ASG Card Documentation

npm install @asgcard/sdk

import { ASGCardClient } from '@asgcard/sdk';

const client = new ASGCardClient({
  privateKey: '<stellar_secret_seed>',
  baseUrl: 'https://api.asgcard.dev',
  rpcUrl: 'https://mainnet.sorobanrpc.com',
});

// One line — SDK handles payment automatically
const card = await client.createCard({
  amount: 10,       // $10 tier
  nameOnCard: 'AI AGENT',
  email: 'agent@example.com',
});

console.log(card.details); // { cardNumber, cvv, expiry, … }

const result = await client.createCard({
  amount: 50,
  nameOnCard: 'AI AGENT',
  email: 'agent@example.com',
});

const result = await client.fundCard({
  amount: 25,
  cardId: 'card-uuid',
});

import {
  ASGCardClient,
  InsufficientBalanceError,
  PaymentError,
  ApiError,
  TimeoutError,
} from '@asgcard/sdk';

try {
  const card = await client.createCard({ amount: 50, nameOnCard: 'AI', email: 'a@b.com' });
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need ${error.required}, have ${error.available}`);
  } else if (error instanceof PaymentError) {
    console.log(`Payment failed: ${error.message}, tx: ${error.txHash}`);
  } else if (error instanceof ApiError) {
    console.log(`Server error ${error.status}:`, error.body);
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

import {
  parseChallenge,
  checkBalance,
  executePayment,
  buildPaymentPayload,
  buildPaymentTransaction,
  handleX402Payment,
} from '@asgcard/sdk';

npx @asgcard/cli onboard -y

asgcard install --client codex      # OpenAI Codex
asgcard install --client claude     # Claude Code
asgcard install --client cursor     # Cursor

[mcp_servers.asgcard]
command = "npx"
args = ["-y", "@asgcard/mcp-server"]

{
  "mcpServers": {
    "asgcard": {
      "command": "npx",
      "args": ["-y", "@asgcard/mcp-server"]
    }
  }
}

npm install -g @asgcard/cli

# Full onboarding (wallet + MCP + skill)
asgcard onboard -y

# Then install for your client:
asgcard install --client codex      # or claude, cursor

# Or step by step:
asgcard wallet create
asgcard wallet info
asgcard card:create -a 10 -n "AGENT ALPHA" -e agent@example.com

curl -X POST https://api.asgcard.dev/cards/create/tier/10 \
  -H "Content-Type: application/json" \
  -d '{"nameOnCard": "AGENT ALPHA", "email": "agent@example.com"}'

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.asgcard.dev/cards/create/tier/10",
    "description": "Create ASG Card with $10 load",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "stellar:pubnet",
    "asset": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75",
    "amount": "172000000",
    "payTo": "GAHYHA55RTD2J4LAVJILTNHWMF2H2YVK5QXLQT3CHCJSVET3VRWPOCW6",
    "maxTimeoutSeconds": 300,
    "extra": { "areFeesSponsored": true }
  }]
}

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "stellar:pubnet"
  },
  "payload": {
    "transaction": "<BASE64_STELLAR_TX_ENVELOPE>"
  }
}

message = "asgcard-auth:<unixTimestamp>"
algorithm = Ed25519 detached
validity window = ±5 minutes

const timestamp = Math.floor(Date.now() / 1000);
const message = `asgcard-auth:${timestamp}`;

// wallet.signMessage should return detached Ed25519 signature bytes
const signature = await wallet.signMessage(new TextEncoder().encode(message));

const response = await fetch('https://api.asgcard.dev/cards', {
  headers: {
    'X-WALLET-ADDRESS': wallet.publicKey,
    'X-WALLET-SIGNATURE': Buffer.from(signature).toString('base64'),
    'X-WALLET-TIMESTAMP': String(timestamp),
  },
});

{
  "success": true,
  "card": { "cardId": "...", "status": "active" },
  "payment": { "txHash": "...", "network": "stellar" },
  "detailsEnvelope": {
    "cardNumber": "5395000000007890",
    "expiryMonth": 12,
    "expiryYear": 2028,
    "cvv": "123",
    "billingAddress": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "oneTimeAccess": true,
    "expiresInSeconds": 300
  }
}

import { v4 as uuid } from 'uuid';

const nonce = uuid();
const timestamp = Math.floor(Date.now() / 1000);
const message = `asgcard-auth:${timestamp}`;
const signature = await wallet.signMessage(new TextEncoder().encode(message));

const res = await fetch('https://api.asgcard.dev/cards/<cardId>/details', {
  headers: {
    'X-WALLET-ADDRESS': wallet.publicKey,
    'X-WALLET-SIGNATURE': Buffer.from(signature).toString('base64'),
    'X-WALLET-TIMESTAMP': String(timestamp),
    'X-AGENT-NONCE': nonce,
  },
});

if (res.status === 409) {
  // Nonce replay detected — generate a new UUID and retry
}
if (res.status === 403) {
  // Card owner has revoked details access
}

HTTP/1.1 409 Conflict
{
  "error": "Nonce already used (replay detected)",
  "code": "REPLAY_REJECTED"
}

HTTP/1.1 403 Forbidden
{
  "error": "Details access revoked by card owner"
}

{ "error": "Human-readable error message" }