AI Skill

mindswap-api-skill/
├── SKILL.md          # Required manifest (frontmatter + instructions)
├── helpers/          # Optional helper scripts
│   └── hmac_sign.py  # Example: HMAC signature helper
└── templates/        # Optional request templates
    └── order.json

# Option A: Upload files (multipart)
curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'files[]=@./mindswap-api-skill/SKILL.md;filename=mindswap-api-skill/SKILL.md;type=text/markdown'

# Option B: Upload zip
curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'files=@./mindswap-api-skill.zip;type=application/zip'

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="o3",
    input="Build a Node.js integration that creates an order via the MindSwap Business API.",
    tools=[{
        "type": "container",
        "container": {
            "environment": {
                "type": "container_auto",
                "skills": [{
                    "type": "skill_reference",
                    "skill_id": "skill_abc123"  # Your uploaded skill ID
                }]
            }
        }
    }]
)

---
name: mindswap-api
description: MindSwap External API integration skill — Business API v3 and x402 API on /api/x402. Covers HMAC auth, x402 payment flow, SIWX reads, routing, onchain execution, SDKs, and idempotency patterns.
---

# MindSwap API Integration Skill

You are an expert integration assistant for the MindSwap External API platform.
MindSwap exposes two REST surfaces—**Business API** and **x402 API**—both served from `https://mindswap.fun`.

## Business API

- **Base path**: `/api/v3`
- **Auth**: HMAC-SHA256 with `X-API-KEY`, `X-API-SIGN`, `X-API-TIMESTAMP`, and `X-API-NONCE`.
  - Compatibility aliases: `X-Signature`, `X-Timestamp`, `X-Nonce`.
  - Mutations require `Idempotency-Key`.
- **Key endpoints**:
  | Method | Path | Purpose |
  |--------|------|---------|
  | GET | /currencies | List supported currencies |
  | GET | /routes | Discover private/offchain and onchain routes |
  | POST | /routes/resolve | Resolve offchain route quote to createToken |
  | POST | /onchain/routes/resolve | Resolve onchain route quote to execution plan |
  | POST | /onchain/executions | Report tx hash or gasless signatures |
  | GET | /onchain/executions/:executionPlanId | Poll onchain execution status |
  | POST | /orders | Create order |
  | GET | /orders/:orderId | Get normalized order detail |
  | POST | /webhooks | Register webhook |
- **Onchain access**: `POST /onchain/routes/resolve` returns `executionAccessToken`. Send it as `X-Onchain-Execution-Access-Token` for report/status.
- **Wormhole flow**: do not use `POST /quotes` for Wormhole. Call `GET /routes?provider=wormhole`, select an Onchain DEX & Bridge route card with `executionType="onchain"`, `executionProvider="wormhole"`, `walletRequired=true`, a `routeQuoteId`, `isAvailable=true`, and positive `expectedOutputAmount`; then call `POST /onchain/routes/resolve`, `POST /onchain/executions`, and `GET /onchain/executions/:executionPlanId`.
- **Rate limits**: per-key request/hour/minute and weighted quotas; inspect `X-RateLimit-*` headers.

## x402 API

- **Base path**: `/api/x402`
- **Headers**:
  - server challenge: `PAYMENT-REQUIRED`
  - client replay: `PAYMENT-SIGNATURE`
  - success metadata: `PAYMENT-RESPONSE`
  - wallet-bound GET reads: `SIGN-IN-WITH-X`
- **Network**: Base mainnet `eip155:8453`
- **Scheme**: `exact`
- **Production facilitator**: Coinbase CDP at `https://api.cdp.coinbase.com/platform/v2/x402`
- **Production env**: `EXTERNAL_API_X402_FACILITATOR_URL` or fallback `X402_FACILITATOR_URL`; `EXTERNAL_API_X402_PAYTO` or fallback `X402_PAYTO`; `EXTERNAL_API_X402_CDP_API_KEY_ID` and `EXTERNAL_API_X402_CDP_API_KEY_SECRET` for Coinbase CDP auth.
- **Do not use in production**: `https://facilitator.x402.org` is testnet-only.
- **Pricing**: current runtime price is `$0.05` for each paid x402 route.
- **Paid endpoints**: `POST /quotes`, `POST /orders`, `POST /orders/:orderId/emergency`, `GET /routes`, `POST /routes/resolve`, `POST /onchain/routes/resolve`, `POST /onchain/executions`, `POST /market-intel/jobs`.
- **Wallet-bound GET routes**: `GET /orders/:orderId`, `GET /onchain/executions/:executionPlanId`, `GET /market-intel/jobs/:jobId`.
- **Onchain access**: onchain resolve returns `executionAccessToken`; send it as `X-Onchain-Execution-Access-Token` for report/status.
- **Wormhole flow**: `POST /quotes` is not the Wormhole path. Use paid `GET /routes?provider=wormhole`, then paid wallet-bound `POST /onchain/routes/resolve`, paid `POST /onchain/executions`, and wallet-bound status polling.

## Common Patterns

- All request/response bodies are JSON (`Content-Type: application/json`).
- Route discovery returns public route cards only; raw provider quote/build internals stay hidden until the resolve endpoint returns the normalized execution plan.
- Business timestamps are Unix epoch seconds.
- Success envelope: `{ "success": true, "data": ... }`.
- Error envelope: `{ "success": false, "error": { "code": "...", "message": "..." } }`.
- Idempotency: supply `Idempotency-Key` on all documented mutation routes that require it.
- Webhook callbacks: configure via dashboard; verify `X-Webhook-Signature`.

## SDK Helpers

**Node.js**: `@mindswap/sdk` currently exposes `createBusinessApiClient()` and legacy `createAgenticApiClient()` naming.
**Python**: `mindswap` currently exposes `BusinessApiClient` and legacy `AgenticApiClient` naming.

Do not invent `createX402ApiClient()` or `X402ApiClient` unless the SDK task has added them. For new x402 integrations, use this OpenAPI contract and the official x402/SIWX client libraries until SDK naming is updated.

When generating Business API integration code, use the SDK if the target language has one. For x402, use the OpenAPI contract and official x402/SIWX libraries unless SDK naming has been explicitly updated.
Prefer idempotency keys on mutations. Handle 429 with exponential back-off.