Content
<p align="center">
<h1 align="center">ASG Card</h1>
<p align="center">
<strong>Your AI agent needs a credit card. ASG Card gives it one — programmatically, in seconds, with USDC or Stripe.</strong>
</p>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@asgcard/sdk"><img src="https://img.shields.io/npm/v/@asgcard/sdk?label=sdk&color=0969da" alt="SDK version"></a>
<a href="https://www.npmjs.com/package/@asgcard/cli"><img src="https://img.shields.io/npm/v/@asgcard/cli?label=cli&color=0969da" alt="CLI version"></a>
<a href="https://www.npmjs.com/package/@asgcard/mcp-server"><img src="https://img.shields.io/npm/v/@asgcard/mcp-server?label=mcp-server&color=0969da" alt="MCP Server version"></a>
<br />
<a href="https://www.npmjs.com/package/@asgcard/sdk"><img src="https://img.shields.io/npm/dm/@asgcard/sdk?label=sdk%20downloads&color=green" alt="SDK downloads"></a>
<a href="https://www.npmjs.com/package/@asgcard/cli"><img src="https://img.shields.io/npm/dm/@asgcard/cli?label=cli%20downloads&color=green" alt="CLI downloads"></a>
<a href="https://www.npmjs.com/package/@asgcard/mcp-server"><img src="https://img.shields.io/npm/dm/@asgcard/mcp-server?label=mcp%20downloads&color=green" alt="MCP downloads"></a>
<br />
<a href="https://github.com/ASGCompute/asgcard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
<a href="https://asgcard.dev"><img src="https://img.shields.io/badge/website-asgcard.dev-blueviolet" alt="Website"></a>
<img src="https://komarev.com/ghpvc/?username=ASGCompute&label=repo%20views&color=blueviolet&style=flat" alt="Visitors">
</p>
<p align="center">
🌐 <a href="README.md">English</a> | <a href="README.zh-CN.md">中文</a>
</p>
---
**ASG Card** is an **agent-first** virtual card platform. AI agents programmatically issue and manage MasterCard virtual cards, paying via **Stellar x402** (USDC) or **Stripe Machine Payments Protocol** (card).
## Quick Start — First Card
```bash
# One-step onboarding (creates wallet, configures MCP, installs skill)
npx @asgcard/cli onboard -y --client codex
# Fund your wallet with USDC on Stellar (address shown by onboard)
# Then:
npx @asgcard/cli card:create -a 10 -n "AI Agent" -e you@email.com
```
## SDK Usage
```typescript
import { ASGCardClient } from "@asgcard/sdk";
const client = new ASGCardClient({
privateKey: "S...", // Stellar secret key
rpcUrl: "https://mainnet.sorobanrpc.com"
});
// Automatically handles: 402 → USDC payment → card creation
const card = await client.createCard({
amount: 10, // $10 card load
nameOnCard: "AI Agent",
email: "agent@example.com"
});
// card.detailsEnvelope = { cardNumber, cvv, expiryMonth, expiryYear }
```
### SDK Methods
| Method | Description |
|--------|-------------|
| `createCard({amount, nameOnCard, email, phone?})` | Issue a virtual card with x402 payment |
| `fundCard({amount, cardId})` | Top up an existing card |
| `listCards()` | List all cards for this wallet |
| `getTransactions(cardId, page?, limit?)` | Get card transaction history |
| `getBalance(cardId)` | Get live card balance |
| `getPricing()` | Get current pricing |
| `health()` | API health check |
## MCP Server (AI Agent Integration)
`@asgcard/mcp-server` exposes **11 tools** for Codex, Claude Code, and Cursor:
| Tool | Description |
|------|-------------|
| `get_wallet_status` | **Use FIRST** — wallet address, USDC balance, readiness |
| `create_card` | Create virtual card (x402 payment) |
| `fund_card` | Fund existing card (x402 payment) |
| `list_cards` | List all wallet cards |
| `get_card` | Get card summary |
| `get_card_details` | Get PAN, CVV, expiry |
| `freeze_card` | Freeze a card |
| `unfreeze_card` | Unfreeze a card |
| `get_pricing` | View pricing |
| `get_transactions` | Card transaction history (real 4payments data) |
| `get_balance` | Live card balance from 4payments |
### MCP Setup
```bash
npx @asgcard/cli install --client codex # or claude, cursor
```
## Architecture
```mermaid
graph TB
subgraph Clients
SDK["@asgcard/sdk<br>(npm, TypeScript)"]
CLI["@asgcard/cli<br>onboard + card ops"]
MCP["@asgcard/mcp-server<br>11 tools"]
TG["Telegram Bot<br>@ASGCardbot"]
WEB["asgcard.dev"]
STRIPE_WEB["stripe.asgcard.dev"]
end
subgraph ASG Infrastructure
API["ASG Card API<br>api.asgcard.dev"]
FAC["x402 Facilitator"]
DB["PostgreSQL"]
end
subgraph Payment Rails
STELLAR["Stellar Pubnet<br>USDC"]
STRIPE["Stripe<br>MPP"]
end
subgraph External
ISSUER["Card Issuer<br>(MasterCard)"]
end
SDK -->|"x402 HTTP"| API
CLI -->|"x402 HTTP"| API
MCP -->|"x402 HTTP"| API
TG -->|"Webhook"| API
WEB -->|"Pricing"| API
STRIPE_WEB -->|"MPP"| API
API -->|"verify/settle"| FAC
API -->|"SQL"| DB
API -->|"REST"| ISSUER
FAC -->|"Soroban RPC"| STELLAR
API -->|"PaymentIntent"| STRIPE
SDK -->|"Sign TX"| STELLAR
```
## Payment Rails
ASG Card supports two payment rails. The card product is identical — only the payment method differs.
### Stellar Edition (x402)
1. **Agent requests a card** → API returns `402 Payment Required` with USDC amount
2. **Agent signs a Stellar USDC transfer** via the SDK
3. **x402 Facilitator verifies and settles** the payment on-chain
4. **API issues a MasterCard** via the card issuer
5. **Card details returned immediately** in the response
Uses: SDK, CLI, MCP server. No human in the loop.
### Stripe Edition (MPP)
1. **Agent creates a payment request** → API returns `approval_required` + `approvalUrl`
2. **Owner opens the approval page** at `stripe.asgcard.dev/approve`
3. **Owner reviews and approves** → Stripe Elements form with real-time pricing
4. **Owner pays via Stripe** → card/Apple Pay/Google Pay
5. **Card created** → agent polls until `completed`
Uses: session-based auth (`X-STRIPE-SESSION`). Human-in-the-loop approval.
## Workspace
| Directory | Description |
|-----------|-------------|
| `/api` | ASG Card API (Express + x402 + Stripe MPP) |
| `/sdk` | `@asgcard/sdk` TypeScript client |
| `/cli` | `@asgcard/cli` CLI with onboarding |
| `/mcp-server` | `@asgcard/mcp-server` MCP server (11 tools) |
| `/web` | Marketing website (asgcard.dev) |
| `/web-stripe` | Stripe edition site (stripe.asgcard.dev) |
| `/docs` | Internal documentation and ADRs |
## API Endpoints
### Public
| Route | Method | Description |
|-------|--------|-------------|
| `/health` | GET | Health check |
| `/pricing` | GET | Pricing info |
| `/cards/tiers` | GET | Pricing info |
| `/supported` | GET | x402 capabilities |
### Stellar x402 (Payment Required)
| Route | Method | Description |
|-------|--------|-------------|
| `/cards/create/tier/:amount` | POST | Create a virtual card |
| `/cards/fund/tier/:amount` | POST | Fund an existing card |
### Wallet Authenticated
| Route | Method | Description |
|-------|--------|-------------|
| `/cards/` | GET | List wallet's cards |
| `/cards/:id` | GET | Card details |
| `/cards/:id/details` | GET | Sensitive data (nonce required) |
| `/cards/:id/transactions` | GET | Card transaction history |
| `/cards/:id/balance` | GET | Live card balance |
| `/cards/:id/freeze` | POST | Freeze card |
| `/cards/:id/unfreeze` | POST | Unfreeze card |
### Stripe MPP (Beta)
| Route | Method | Description |
|-------|--------|-------------|
| `/stripe-beta/session` | POST | Create managed session |
| `/stripe-beta/payment-requests` | POST | Create payment request |
| `/stripe-beta/payment-requests/:id` | GET | Poll request status |
| `/stripe-beta/approve/:id` | GET/POST | Approval page data / approve or reject |
| `/stripe-beta/approve/:id/complete` | POST | Complete payment (MPP credential) |
| `/stripe-beta/cards` | GET | List session's cards |
| `/stripe-beta/cards/:id/details` | GET | Card details (nonce required) |
## Pricing
**Simple, transparent, no hidden fees.**
- **$10** flat card creation (no initial load required)
- **3.5%** on every top-up
That's it. Load any amount from $5 to $5,000.
> Create card with no load → **$10**. Create card loaded with $100 → **$113.50**. Top up $200 later → just **$207**.
> Same pricing on both Stellar and Stripe rails.
## Telegram Bot (@ASGCardbot)
Link your wallet to Telegram for card management:
| Command | Description |
|---------|-------------|
| `/start` | Welcome / Link account |
| `/mycards` | List your cards |
| `/faq` | FAQ |
| `/support` | Support |
## Security
- Card details encrypted at rest with **AES-256-GCM**
- Agent nonce-based anti-replay protection (5 reads/hour)
- Wallet signature authentication (Stellar edition)
- Session-based authentication with beta gates (Stripe edition)
- Stripe session keys redacted from logs
- Telegram webhook secret validation
- Ops endpoints protected by API key + IP allowlist
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and check out issues labeled [`good first issue`](https://github.com/ASGCompute/asgcard/labels/good%20first%20issue) to get started.
This project follows our [Code of Conduct](CODE_OF_CONDUCT.md).
## License
MIT
---
<p align="center">
<a href="https://star-history.com/#ASGCompute/asgcard&Date">
<img src="https://api.star-history.com/svg?repos=ASGCompute/asgcard&type=Date" width="600" alt="Star History Chart">
</a>
</p>
