back
loading skill details...
This skill should be used when the user asks to "provision GPU instance", "spin up a cloud server", "list compute plans", "browse GPU pricing", "extend compu...
---
name: x402-compute
version: 1.4.1
description: |
This skill should be used when the user asks to "provision GPU instance",
"spin up a cloud server", "list compute plans", "browse GPU pricing",
"extend compute instance", "resize compute instance", "destroy server instance", "check instance status",
"list my instances", "top up compute credits", "check credit balance", or manage x402 Singularity Compute / x402Compute
infrastructure. Handles GPU and VPS provisioning across Vultr and DigitalOcean
with USDC payment on Base or Solana, USDm payment on MegaETH via x402,
optional MPP/Mppx payment flows, or pre-loaded USD credits for payment-free
provisioning and extending. Includes optional OWS-backed auth and management flows.
homepage: https://studio.x402layer.cc/docs/agentic-access/x402-compute
metadata:
clawdbot:
emoji: "🖥️"
homepage: https://compute.x402layer.cc
os:
- linux
- darwin
requires:
bins:
- python3
env:
- name: PRIVATE_KEY
description: EVM private key for Base/MegaETH payment signing (use a dedicated low-balance wallet)
sensitive: true
optional: true
- name: WALLET_ADDRESS
description: EVM wallet address corresponding to PRIVATE_KEY
optional: true
- name: SOLANA_SECRET_KEY
description: Solana signer key for Solana payment signing (use a dedicated low-balance wallet)
sensitive: true
optional: true
- name: SOLANA_WALLET_ADDRESS
description: Solana wallet address
optional: true
- name: COMPUTE_API_KEY
description: Reusable API key for management endpoints (created via POST /compute/api-keys)
sensitive: true
optional: true
- name: COMPUTE_AUTH_CHAIN
description: Auth chain override — base, megaeth, or solana
optional: true
- name: OWS_BIN
description: Explicit path to a locally installed OWS binary (avoids runtime npx downloads)
optional: true
allowed-tools:
- Read
- Write
- Edit
- Bash
- WebFetch
---
# x402 Singularity Compute
Provision, manage, resize, and extend GPU/VPS instances on Vultr or DigitalOcean paid with x402, MPP, or pre-loaded credits.
**Base URL:** `https://compute.x402layer.cc`
**Providers:** Vultr • DigitalOcean
**x402 Networks:** Base (EVM) • Solana • MegaETH
**x402 Currency:** USDC (Base/Solana) • USDm (MegaETH)
**MPP Methods:** Tempo • Stripe/card when enabled by the service
**Credits:** Pre-load USD via x402 topup, then provision/extend with `use_credits: true`
**Protocol:** HTTP 402 Payment Required (`X-Payment` for x402, `Authorization: Payment` for MPP)
**Access Note:** Preferred access is SSH public key. If no SSH key is provided, a one-time password fallback can be fetched once via API.
**DigitalOcean Note:** DigitalOcean instances require SSH key access because one-time root passwords are not exposed through the DigitalOcean API.
---
## Quick Start
### 1. Install Dependencies
```bash
pip install -r {baseDir}/requirements.txt
```
### 2. Choose Wallet Mode
#### Option A: Direct signing keys (Base, MegaETH, or Solana)
> **Use a dedicated low-balance wallet.** Never use your primary custody wallet.
```bash
# Base (EVM) — same keys work for MegaETH
export PRIVATE_KEY=<your-evm-private-key>
export WALLET_ADDRESS=<your-evm-wallet-address>
# MegaETH (uses same EVM keys as Base)
export PRIVATE_KEY=<your-evm-private-key>
export WALLET_ADDRESS=<your-evm-wallet-address>
export COMPUTE_AUTH_CHAIN="megaeth"
# Solana
export SOLANA_SECRET_KEY=<your-solana-secret-key>
export SOLANA_WALLET_ADDRESS=<your-solana-wallet-address>
export COMPUTE_AUTH_CHAIN="solana"
```
#### Option B: OpenWallet / OWS (optional-first)
```bash
npm install -g @open-wallet-standard/core@0.5.0
export OWS_WALLET="compute-wallet"
export COMPUTE_AUTH_MODE="ows"
```
Create `COMPUTE_API_KEY` (optional) for management endpoints:
```bash
python {baseDir}/scripts/create_api_key.py --label "my-agent"
```
OWS is best for compute auth and routine management flows. Direct x402 provision and extend still use local payment-signing paths. MPP provision/extend should use `mppx` or Tempo Wallet.
Resize is a management action, not a second payment flow. The API preserves remaining prepaid dollar credit by recalculating `expires_at` for the target hourly rate after the provider accepts the resize.
---
## ⚠️ Security Notice
> **IMPORTANT**: This skill handles private keys for signing blockchain transactions.
>
> - **Never use your primary custody wallet** - Create a dedicated wallet with limited funds
> - **Private keys are used locally only** - They sign transactions locally and are never transmitted
> - **For testing**: Use a throwaway wallet with minimal USDC/USDm
---
## Scripts Overview
| Script | Purpose |
|--------|---------|
| `browse_plans.py` | List available GPU/VPS plans with pricing |
| `browse_regions.py` | List deployment regions |
| `provision.py` | Provision a new instance (x402 payment, `--months` or `--days`) |
| `create_api_key.py` | Create an API key for agent access (optional) |
| `list_instances.py` | List your active instances |
| `instance_details.py` | Get details for a specific instance |
| `get_one_time_password.py` | Retrieve one-time root password fallback |
| `extend_instance.py` | Extend instance lifetime (x402 payment) |
| `resize_instance.py` | Resize an instance in place (compute auth only) |
| `destroy_instance.py` | Destroy an instance |
| `ows_cli.py` | Run OpenWallet / OWS wallet, sign-message, and key commands |
| `solana_signing.py` | Internal helper for Solana x402 payment signing |
---
## Instance Lifecycle
```
Browse Plans → Choose Provider/Plan → Provision (x402/MPP/Credits) → Active → Extend / Destroy → Expired
```
Instances expire after their prepaid duration. Extend before expiry to keep them running.
---
## Workflows
### A. Browse and Provision
```bash
# List GPU plans
python {baseDir}/scripts/browse_plans.py
# Filter by type (gpu/vps/high-performance)
python {baseDir}/scripts/browse_plans.py --type vcg
# Check available regions
python {baseDir}/scripts/browse_regions.py
# Generate a dedicated SSH key once (recommended for agents)
ssh-keygen -t ed25519 -N "" -f ~/.ssh/x402_compute
# Provision an instance for 1 month (triggers x402 payment)
python {baseDir}/scripts/provision.py vcg-a100-1c-2g-6gb lax --months 1 --label "my-gpu" --ssh-key-file ~/.ssh/x402_compute.pub
# DigitalOcean plans are prefixed with do:
# They require SSH key access.
python {baseDir}/scripts/provision.py do:s-1vcpu-1gb nyc3 --days 1 --label "do-test" --ssh-key-file ~/.ssh/x402_compute.pub
# Provision a daily instance (cheaper, use-and-throw)
python {baseDir}/scripts/provision.py vc2-1c-1gb ewr --days 1 --label "test-daily" --ssh-key-file ~/.ssh/x402_compute.pub
# Provision for 3 days
python {baseDir}/scripts/provision.py vc2-1c-1gb ewr --days 3 --label "short-task" --ssh-key-file ~/.ssh/x402_compute.pub
# Provision on Solana
python {baseDir}/scripts/provision.py vc2-1c-1gb ewr --months 1 --label "my-sol-vps" --network solana --ssh-key-file ~/.ssh/x402_compute.pub
# Provision on MegaETH (pays with USDm)
python {baseDir}/scripts/provision.py vc2-1c-1gb ewr --months 1 --label "my-mega-vps" --network megaeth --ssh-key-file ~/.ssh/x402_compute.pub
# Provision via MPP / mppx (Tempo by default; Stripe/card if your mppx config supports it)
npx mppx https://compute.x402layer.cc/compute/provision \
-X POST \
-J '{"plan":"vc2-1c-1gb","region":"ewr","os_id":2284,"label":"mpp-vps","prepaid_hours":24,"ssh_public_key":"ssh-ed25519 AAAA... agent"}'
# If the response includes management_api_key, store it for later instance management:
export COMPUTE_API_KEY="x402c_..."
# ⚠️ After provisioning, wait 2-3 minutes for Vultr to complete setup
# Then fetch your instance details (IP, status):
python {baseDir}/scripts/instance_details.py <instance_id>
```
### B. Manage Instances
```bash
# Optional: create a reusable API key (avoids message signing each request)
python {baseDir}/scripts/create_api_key.py --label "my-agent"
# List all your instances
python {baseDir}/scripts/list_instances.py
# Get details for one instance
python {baseDir}/scripts/instance_details.py <instance_id>
# Optional fallback if no SSH key was provided during provisioning
python {baseDir}/scripts/get_one_time_password.py <instance_id>
# Extend by 1 day
python {baseDir}/scripts/extend_instance.py <instance_id> --hours 24
# Extend by 1 month
python {baseDir}/scripts/extend_instance.py <instance_id> --hours 720
# Extend on Solana
python {baseDir}/scripts/extend_instance.py <instance_id> --hours 720 --network solana
# Extend on MegaETH (pays with USDm)
python {baseDir}/scripts/extend_instance.py <instance_id> --hours 720 --network megaeth
# Extend via MPP. MPP extension requires compute auth; use the management API key
# returned from MPP provisioning or normal wallet signature auth.
npx mppx https://compute.x402layer.cc/compute/instances/<instance_id>/extend \
-X POST \
-H "X-API-Key: $COMPUTE_API_KEY" \
-J '{"extend_hours":720}'
# Resize via bundled helper script
python {baseDir}/scripts/resize_instance.py <instance_id> vc2-2c-4gb
# Resize in place with management auth only (no x402 or MPP payment)
curl -X POST https://compute.x402layer.cc/compute/instances/<instance_id>/resize \
-H "Content-Type: application/json" \
-H "X-API-Key: $COMPUTE_API_KEY" \
-d '{"plan":"vc2-2c-4gb"}'
# DigitalOcean disk growth is irreversible and must be confirmed explicitly
curl -X POST https://compute.x402layer.cc/compute/instances/<instance_id>/resize \
-H "Content-Type: application/json" \
-H "X-API-Key: $COMPUTE_API_KEY" \
-d '{"plan":"do:s-2vcpu-4gb","confirm_disk_resize":true}'
# Destroy
python {baseDir}/scripts/destroy_instance.py <instance_id>
```
### C. OpenWallet / OWS
```bash
# List local OWS wallets
python {baseDir}/scripts/ows_cli.py wallet-list
# Sign a Base-compatible compute auth message
python {baseDir}/scripts/ows_cli.py sign-message --chain eip155:8453 --wallet compute-wallet --message "hello"
# Sign a MegaETH-compatible compute auth message
python {baseDir}/scripts/ows_cli.py sign-message --chain eip155:4326 --wallet compute-wallet --message "hello"
# Sign a Solana-compatible compute auth message
python {baseDir}/scripts/ows_cli.py sign-message --chain solana --wallet compute-wallet --message "hello"
# Create an OWS agent key
python {baseDir}/scripts/ows_cli.py key-create --name codex-compute --wallet compute-wallet
```
### D. Credits (payment-free provisioning)
```bash
# Top up credits via x402 payment (one-time)
curl -X POST https://compute.x402layer.cc/compute/credits/topup \
-H "Content-Type: application/json" \
-H "X-API-Key: $COMPUTE_API_KEY" \
-d '{"amount": 100, "network": "base"}'
# Returns 402 → pay → credits added to wallet balance
# Check credit balance
curl https://compute.x402layer.cc/compute/credits/balance \
-H "X-API-Key: $COMPUTE_API_KEY"
# Provision using credits (no x402/MPP payment needed)
curl -X POST https://compute.x402layer.cc/compute/provision \
-H "Content-Type: application/json" \
-H "X-API-Key: $COMPUTE_API_KEY" \
-d '{
"plan": "vc2-1c-1gb",
"region": "ewr",
"os_id": 2284,
"label": "credit-vps",
"prepaid_hours": 720,
"ssh_public_key": "ssh-ed25519 AAAA... agent",
"use_credits": true
}'
# Extend using credits
curl -X POST https://compute.x402layer.cc/compute/instances/<instance_id>/extend \
-H "Content-Type: application/json" \
-H "X-API-Key: $COMPUTE_API_KEY" \
-d '{"extend_hours": 720, "use_credits": true}'
```
Credits are scoped per wallet. If the cloud provider rejects the instance after credits are deducted, the full amount is automatically refunded.
---
## x402 Payment Flow
1. Request provision/extend → server returns `HTTP 402` with payment requirements
2. Script signs payment locally:
- Base: USDC `TransferWithAuthorization` (EIP-712)
- MegaETH: USDm ERC-2612 `permit` (EIP-712) — gasless for the user, facilitator settles on-chain
- Solana: signed SPL transfer transaction payload
3. Script resends request with `X-Payment` header containing signed payload
4. Server verifies payment, settles on-chain, provisions/extends instance
MegaETH uses an embedded facilitator (no external CDP dependency). The user signs an off-chain ERC-2612 permit, and the facilitator calls `permit()` + `transferFrom()` on MegaETH (~10ms blocks, near-zero gas).
For Solana, transient facilitator failures can happen. Retry once or twice if you get a temporary 5xx verify error.
## MPP Payment Flow
MPP is available side-by-side with x402 on the same paid endpoints.
1. Request provision/extend -> server returns `HTTP 402` with `WWW-Authenticate: Payment`
2. `mppx` or Tempo Wallet creates an MPP credential
3. Client retries with `Authorization: Payment ...`
4. Server verifies the MPP payment, provisions/extends the instance, and returns `Payment-Receipt`
Notes:
- `POST /compute/provision` can be paid via MPP without wallet auth. In that case the response includes `management_api_key`; store it because it is shown once and is required for later management.
- `POST /compute/instances/:id/extend` via MPP requires compute auth, usually `X-API-Key: $COMPUTE_API_KEY`.
- `POST /compute/instances/:id/resize` uses compute auth only. It preserves remaining prepaid value by changing expiry instead of charging again.
- x402 remains fully supported through the Python scripts and `X-Payment` header flow.
- MPP methods are service-configured. Tempo is used by default by `mppx`; Stripe/card requires a Stripe-capable MPP client/config.
---
## Plan Types
| Type | Plan Prefix | Description |
|------|-------------|-------------|
| GPU | `vcg-*` | GPU-accelerated (A100, H100, etc.) |
| VPS | `vc2-*` | Standard cloud compute |
| High-Perf | `vhp-*` | High-performance dedicated |
| Dedicated | `vdc-*` | Dedicated bare-metal |
| DigitalOcean | `do:*` | DigitalOcean Droplets (provider-prefixed size slugs) |
---
## Environment Reference
| Variable | Required For | Description |
|----------|--------------|-------------|
| `PRIVATE_KEY` | Base/MegaETH payment signing | EVM private key (0x...) |
| `WALLET_ADDRESS` | Base/MegaETH direct-signing mode | EVM wallet address (0x...) |
| `SOLANA_SECRET_KEY` | Solana direct-signing mode | Solana signer key (base58 or JSON byte array) |
| `SOLANA_WALLET_ADDRESS` | Solana direct-signing mode | Solana wallet address (optional if derivable from secret) |
| `COMPUTE_AUTH_CHAIN` | Chain auth override | `base`, `megaeth`, or `solana` |
| `COMPUTE_API_KEY` | Optional | Reusable API key for compute management endpoints |
| `COMPUTE_AUTH_MODE` | Optional | `auto`, `private-key`, or `ows` |
| `OWS_WALLET` | OWS auth mode | OWS wallet name or ID |
| `OWS_BIN` | OWS auth mode | Optional explicit path to the `ows` executable |
| `COMPUTE_API_KEY` | MPP/no-wallet management | API key returned once after an MPP provision without wallet auth |
---
## API Reference
For full endpoint details, see:
- [references/api-reference.md](references/api-reference.md)
- [references/openwallet-ows.md](references/openwallet-ows.md)
---
## Resources
- 📖 **Documentation:** [studio.x402layer.cc/docs/agentic-access/x402-compute](https://studio.x402layer.cc/docs/agentic-access/x402-compute)
- 🖥️ **Compute Dashboard:** [compute.x402layer.cc](https://compute.x402layer.cc)
- 🌐 **x402 Studio:** [studio.x402layer.cc](https://studio.x402layer.cc)
---
## OWS scope note
OWS support is optional-first in this release:
- use it for compute auth and management/API-key flows
- keep direct Base, MegaETH, or Solana signing keys for the paid provision and extend flows
- resize, list, details, password fallback, and destroy work with normal compute auth / API keys
don't have the plugin yet? install it then click "run inline in claude" again.