Skip to content

Commit 14f84fb

Browse files
plagtechplagtech
committed
feat: add spraay sandbox — crypto payment layer for autonomous agents
Signed-off-by: plagtech <mngoswp@gmail.com>
1 parent 88812df commit 14f84fb

File tree

8 files changed

+796
-0
lines changed

8 files changed

+796
-0
lines changed

‎sandboxes/spraay/Dockerfile‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
ARG BASE_IMAGE=ghcr.io/nvidia/openshell-community/sandboxes/base:latest
2+
FROM ${BASE_IMAGE}
3+
4+
# ── Spraay x402 Payment Toolkit ──────────────────────────────────────────────
5+
# Pre-configured sandbox for AI agent crypto payments via the x402 protocol.
6+
# Supports 13 blockchains, 76+ gateway endpoints, batch payments, escrow,
7+
# payroll, token swaps, and Robot Task Protocol (RTP).
8+
9+
# Install Node.js (required for ethers.js wallet operations)
10+
USER root
11+
RUN apt-get update && apt-get install -y --no-install-recommends \
12+
curl \
13+
jq \
14+
&& curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
15+
&& apt-get install -y --no-install-recommends nodejs \
16+
&& npm install -g ethers@6 \
17+
&& apt-get clean && rm -rf /var/lib/apt/lists/*
18+
19+
# Install Python dependencies for wallet and signing operations
20+
USER sandbox
21+
RUN pip install --no-cache-dir \
22+
httpx \
23+
eth-account \
24+
web3 \
25+
pynacl \
26+
base58
27+
28+
# ── Spraay CLI wrapper ──────────────────────────────────────────────────────
29+
COPY spraay.sh /usr/local/bin/spraay
30+
USER root
31+
RUN chmod +x /usr/local/bin/spraay
32+
USER sandbox
33+
34+
# ── Agent skills ─────────────────────────────────────────────────────────────
35+
COPY skills/ /sandbox/.agents/skills/
36+
37+
# ── Default environment ──────────────────────────────────────────────────────
38+
ENV SPRAAY_GATEWAY_URL=https://gateway.spraay.app
39+
ENV SPRAAY_CHAIN=base
40+
41+
# ── Healthcheck ──────────────────────────────────────────────────────────────
42+
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
43+
CMD curl -sf ${SPRAAY_GATEWAY_URL}/health || exit 1

‎sandboxes/spraay/README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Spraay — Crypto Payment Sandbox for OpenShell
2+
3+
OpenShell sandbox image pre-configured with [Spraay](https://spraay.app) for AI agent crypto payments via the x402 protocol.
4+
5+
## What's Included
6+
7+
| Component | Description |
8+
|-----------|-------------|
9+
| **Spraay CLI** | Shell wrapper for 76+ paid gateway endpoints across 13 blockchains |
10+
| **x402 Protocol** | HTTP 402-based micropayment protocol — agents pay per request with USDC |
11+
| **Agent Skills** | Pre-built skills for batch payments, escrow, payroll, token swaps, and Robot Task Protocol (RTP) |
12+
| **Multi-Chain** | Base, Ethereum, Arbitrum, Polygon, BNB, Avalanche, Solana, Bitcoin, Stacks, Unichain, Plasma, BOB, Bittensor |
13+
14+
## Quick Start
15+
16+
### Using the pre-built image
17+
18+
```bash
19+
openshell sandbox create --from spraay -- claude
20+
```
21+
22+
### Building locally
23+
24+
```bash
25+
docker build -t openshell-spraay \
26+
--build-arg BASE_IMAGE=ghcr.io/nvidia/openshell-community/sandboxes/base:latest .
27+
```
28+
29+
Then launch:
30+
31+
```bash
32+
openshell sandbox create --from openshell-spraay -- claude
33+
```
34+
35+
## Environment Variables
36+
37+
| Variable | Required | Description |
38+
|----------|----------|-------------|
39+
| `SPRAAY_GATEWAY_URL` | No | Gateway URL (default: `https://gateway.spraay.app`) |
40+
| `SPRAAY_PAYMENT_ADDRESS` | Yes | Your wallet address for x402 payments |
41+
| `SPRAAY_CHAIN` | No | Default chain (default: `base`) |
42+
43+
## Skills
44+
45+
The sandbox ships with agent skills in `.agents/skills/`:
46+
47+
| Skill | Description |
48+
|-------|-------------|
49+
| `spraay-payments` | Batch send tokens to multiple recipients on any supported chain |
50+
| `spraay-escrow` | Create and manage escrow contracts with milestone-based releases |
51+
| `spraay-rtp` | Robot Task Protocol — hire robots and IoT devices via x402 micropayments |
52+
| `spraay-gateway` | Query gateway endpoints, check pricing, discover available routes |
53+
54+
## Network Policy
55+
56+
The default network policy allows egress to:
57+
58+
- `gateway.spraay.app` — Spraay x402 gateway (HTTPS)
59+
- `*.infura.io` — RPC provider (HTTPS)
60+
- `*.alchemy.com` — RPC provider (HTTPS)
61+
- `*.base.org` — Base chain RPC (HTTPS)
62+
63+
All other egress is denied by default. Customize via OpenShell policy overrides.
64+
65+
## How x402 Works Inside the Sandbox
66+
67+
1. Agent calls a Spraay gateway endpoint (e.g., `/v1/batch-send`)
68+
2. Gateway returns HTTP `402 Payment Required` with a payment header
69+
3. Agent signs USDC payment using its configured wallet
70+
4. Gateway verifies payment on-chain and executes the request
71+
5. Agent receives the result
72+
73+
The sandbox enforces that all payment signing happens within the isolated environment. Private keys never leave the sandbox boundary.
74+
75+
## Use Cases
76+
77+
- **Autonomous payroll**: Agent runs scheduled batch payments to employees/contractors
78+
- **Escrow automation**: Agent creates milestone-based escrow for freelance work
79+
- **Robot hiring**: Agent uses RTP to commission physical tasks from IoT devices
80+
- **Multi-chain treasury**: Agent manages token distributions across 13+ chains
81+
- **DCA/Scheduled swaps**: Agent executes dollar-cost averaging strategies
82+
83+
## Resources
84+
85+
- [Spraay Gateway Docs](https://docs.spraay.app)
86+
- [x402 Protocol Spec](https://www.x402.org)
87+
- [Spraay MCP Server](https://smithery.ai/server/@plagtech/spraay-x402-mcp)
88+
- [OpenShell Documentation](https://docs.nvidia.com/openshell/latest/index.html)
89+
90+
## License
91+
92+
Apache 2.0 — see [LICENSE](../../LICENSE).

‎sandboxes/spraay/policy.yaml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# Spraay Sandbox Network Policy
2+
# This policy allows egress only to the Spraay gateway and required
3+
# blockchain RPC providers. All other egress is denied by default.
4+
#
5+
# Apply with: openshell policy set <sandbox-name> --policy policy.yaml --wait
6+
7+
version: "1"
8+
9+
# ── Spraay Gateway ───────────────────────────────────────────────────────────
10+
spraay_gateway:
11+
destination: "gateway.spraay.app"
12+
port: 443
13+
protocol: tcp
14+
action: allow
15+
note: "Spraay x402 payment gateway — all API requests route here"
16+
17+
spraay_docs:
18+
destination: "docs.spraay.app"
19+
port: 443
20+
protocol: tcp
21+
action: allow
22+
note: "Spraay API documentation"
23+
24+
# ── Blockchain RPC Providers ─────────────────────────────────────────────────
25+
infura_rpc:
26+
destination: "*.infura.io"
27+
port: 443
28+
protocol: tcp
29+
action: allow
30+
note: "Infura — Ethereum, Polygon, Arbitrum, Optimism RPC"
31+
32+
alchemy_rpc:
33+
destination: "*.alchemy.com"
34+
port: 443
35+
protocol: tcp
36+
action: allow
37+
note: "Alchemy — multi-chain RPC provider"
38+
39+
base_rpc:
40+
destination: "*.base.org"
41+
port: 443
42+
protocol: tcp
43+
action: allow
44+
note: "Base chain public RPC"
45+
46+
quicknode_rpc:
47+
destination: "*.quiknode.pro"
48+
port: 443
49+
protocol: tcp
50+
action: allow
51+
note: "QuickNode — multi-chain RPC provider"
52+
53+
# ── Coinbase (x402 payment verification) ─────────────────────────────────────
54+
coinbase_cdp:
55+
destination: "*.coinbase.com"
56+
port: 443
57+
protocol: tcp
58+
action: allow
59+
note: "Coinbase CDP — x402 payment facilitation and verification"
60+
61+
# ── Solana RPC ───────────────────────────────────────────────────────────────
62+
solana_rpc:
63+
destination: "*.solana.com"
64+
port: 443
65+
protocol: tcp
66+
action: allow
67+
note: "Solana mainnet RPC"
68+
69+
helius_rpc:
70+
destination: "*.helius-rpc.com"
71+
port: 443
72+
protocol: tcp
73+
action: allow
74+
note: "Helius — Solana RPC provider"
75+
76+
# ── Bitcoin / Stacks ─────────────────────────────────────────────────────────
77+
blockstream_api:
78+
destination: "blockstream.info"
79+
port: 443
80+
protocol: tcp
81+
action: allow
82+
note: "Blockstream — Bitcoin block explorer API"
83+
84+
stacks_api:
85+
destination: "*.stacks.co"
86+
port: 443
87+
protocol: tcp
88+
action: allow
89+
note: "Stacks blockchain API"
90+
91+
# ── Deny everything else ─────────────────────────────────────────────────────
92+
# OpenShell default policy denies all egress not explicitly allowed above.

‎sandboxes/spraay/skills/spraay-escrow.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Spraay Escrow Skill
2+
3+
Create and manage on-chain escrow contracts with milestone-based fund releases.
4+
5+
## When to Use
6+
7+
Use this skill when the user or agent needs to:
8+
9+
- Hold funds in escrow between two parties
10+
- Release payments based on milestone completion
11+
- Create trustless payment agreements for freelance or contract work
12+
- Automate conditional fund releases
13+
14+
## How It Works
15+
16+
1. **Create**: Deposit tokens into an escrow smart contract with defined milestones
17+
2. **Monitor**: Check escrow status and milestone completion
18+
3. **Release**: Release funds when milestones are verified
19+
4. **Refund**: Return funds if conditions are not met
20+
21+
## Commands
22+
23+
### Create an escrow
24+
```bash
25+
spraay escrow-create '{
26+
"depositor": "0xYourAddress",
27+
"beneficiary": "0xFreelancerAddress",
28+
"token": "USDC",
29+
"totalAmount": "500.0",
30+
"chain": "base",
31+
"milestones": [
32+
{"description": "Design mockups delivered", "amount": "150.0"},
33+
{"description": "Frontend implementation", "amount": "200.0"},
34+
{"description": "Testing and deployment", "amount": "150.0"}
35+
]
36+
}'
37+
```
38+
39+
### Check escrow status
40+
```bash
41+
spraay escrow-status <escrow-id>
42+
```
43+
44+
### Release milestone funds
45+
```bash
46+
spraay escrow-release <escrow-id>
47+
```
48+
49+
## Important Notes
50+
51+
- Escrow creation requires sufficient token balance plus the x402 gateway fee
52+
- Milestone releases are sequential by default
53+
- Both parties can view escrow status on-chain
54+
- Escrow contracts are non-custodial — funds are held by the smart contract, not by Spraay
55+
56+
## Error Handling
57+
58+
- HTTP 402: Payment required for gateway fee
59+
- HTTP 409: Escrow already exists or milestone already released
60+
- HTTP 404: Escrow ID not found

‎sandboxes/spraay/skills/spraay-gateway.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Spraay Gateway Skill
2+
3+
Query the Spraay x402 gateway to discover available endpoints, check pricing, and understand supported chains and tokens.
4+
5+
## When to Use
6+
7+
Use this skill when the user or agent needs to:
8+
9+
- See all available Spraay gateway routes and their pricing
10+
- Check which chains and tokens are supported
11+
- Verify gateway health and connectivity
12+
- Understand x402 payment requirements before making a request
13+
14+
## Commands
15+
16+
### Check gateway health
17+
```bash
18+
spraay health
19+
```
20+
21+
### Get gateway info
22+
```bash
23+
spraay info
24+
```
25+
26+
### List all routes with pricing
27+
```bash
28+
spraay routes
29+
```
30+
31+
### List supported chains
32+
```bash
33+
spraay chains
34+
```
35+
36+
### Make a raw API call
37+
```bash
38+
spraay raw GET /v1/some-endpoint
39+
spraay raw POST /v1/some-endpoint '{"key": "value"}'
40+
```
41+
42+
## Gateway Overview
43+
44+
The Spraay gateway at `gateway.spraay.app` exposes 76+ paid endpoints across 16 categories:
45+
46+
| Category | Description | Example Endpoints |
47+
|----------|-------------|-------------------|
48+
| 1. Batch Payments | Multi-recipient token sends | `/v1/batch-send` |
49+
| 2. Token Swaps | DEX aggregation | `/v1/swap`, `/v1/quote` |
50+
| 3. Escrow | Milestone-based contracts | `/v1/escrow/*` |
51+
| 4. Payroll | Recurring payment runs | `/v1/payroll/*` |
52+
| 5. Price Oracle | Token pricing data | `/v1/price` |
53+
| 6. Balance | Wallet balance queries | `/v1/balance` |
54+
| 7. NFT | Mint and transfer NFTs | `/v1/nft/*` |
55+
| 8. Bridge | Cross-chain transfers | `/v1/bridge/*` |
56+
| 9. Staking | Stake and unstake tokens | `/v1/staking/*` |
57+
| 10. Governance | DAO proposal tools | `/v1/governance/*` |
58+
| 11. Analytics | On-chain data queries | `/v1/analytics/*` |
59+
| 12. AI Inference | Proxy to AI models | `/v1/inference/*` |
60+
| 13. Wallet | Wallet management | `/v1/wallet/*` |
61+
| 14. Agent Wallet | Managed agent wallets | `/v1/agent-wallet/*` |
62+
| 15. RTP | Robot Task Protocol | `/v1/rtp/*` |
63+
| 16. Identity | On-chain identity | `/v1/identity/*` |
64+
65+
## Pricing Tiers
66+
67+
- **Free endpoints**: `/health`, `/v1/info`, `/v1/routes`, `/v1/chains` (11 total)
68+
- **Standard**: $0.01–$0.05 per request (most query endpoints)
69+
- **Premium**: $0.05–$0.25 per request (escrow, bridge, payroll execution)
70+
71+
## x402 Payment Flow
72+
73+
All paid endpoints use the HTTP 402 protocol:
74+
75+
1. Client sends a request without payment
76+
2. Gateway responds with `402 Payment Required` + payment details header
77+
3. Client signs a USDC payment transaction
78+
4. Client resends request with the signed payment in the header
79+
5. Gateway verifies payment and processes the request
80+
81+
The payment address for all gateway requests:
82+
`0xAd62f03C7514bb8c51f1eA70C2b75C37404695c8`
83+
84+
## Important Notes
85+
86+
- Free endpoints do not require x402 payment
87+
- The gateway is chain-agnostic — specify the target chain per request
88+
- Rate limiting applies: check `X-RateLimit-*` response headers
89+
- The Spraay MCP server (`@plagtech/spraay-x402-mcp`) wraps all these endpoints for LLM tool use

0 commit comments

Comments
 (0)