Vestra Forge API Reference

Base URL (Demo): https://forge.vestralabs.xyz/api Version: v1 (semantic: MAJOR.MINOR.PATCH) Auth: Bearer token (JWT) for user endpoints + wallet signature for sensitive actions (deploy, publish). Networks: devnet, mainnet-beta Content-Type: application/json

---

Authentication

POST /v1/auth/login

Email/password or wallet challenge (both supported).

Body (email)

{ "email": "[email protected]", "password": "••••••" }

Body (wallet)

{ "address": "FAicX…Zjke", "signedMessage": "base64", "nonce": "uuid" }

Response

{
  "user": { "id": "usr_123", "email": "[email protected]" },
  "token": "jwt-token",
  "expiresIn": 3600
}

GET /v1/auth/nonce

Returns a nonce for wallet-based login/challenge.

---

Users & Workspaces

GET /v1/me

Returns profile, plan, and default workspace.

GET /v1/workspaces

List workspaces current user can access.

POST /v1/workspaces

Create a workspace.

{ "name": "Vestra Team", "billingPlan": "free|pro|enterprise" }

---

Projects

GET /v1/projects?workspaceId=ws_123&status=draft|published&query=...&page=1&limit=20

Search & paginate projects.

Project Model

{
  "id": "proj_123",
  "name": "Forge Demo",
  "description": "Set parameters and generate contracts.",
  "labels": ["Token","Devnet","Draft"],
  "network": "devnet",
  "status": "draft|published|archived",
  "updatedAt": "2025-09-15T20:30:00Z",
  "createdBy": "usr_123"
}

POST /v1/projects

{
  "workspaceId": "ws_123",
  "name": "Quick Trade Analysis",
  "description": "Token analysis flows",
  "network": "devnet"
}

GET /v1/projects/{projectId}

Retrieve project + last canvas snapshot.

PATCH /v1/projects/{projectId}

Rename, update network, labels, etc.

DELETE /v1/projects/{projectId}

Soft delete (archivable).

---

Canvas Graph

The canvas is a directed graph of nodes (modules) and edges (typed connections). Think: JSON IR that compiles to Anchor/Rust.

GET /v1/projects/{projectId}/canvas

Returns the current graph.

Canvas Schema

{
  "version": "1.1",
  "nodes": [
    {
      "id": "node_spl_token_mint_1",
      "type": "splTokenMint",
      "title": "SPL Token Mint",
      "params": {
        "name": "Vestra Token",
        "symbol": "VST",
        "decimals": 9,
        "initialSupply": "1000000000000",
        "mintAuthority": "wallet",
        "freezeAuthority": null
      },
      "io": {
        "inputs": [{"key":"payer","type":"pubkey"}],
        "outputs":[{"key":"mint","type":"pubkey"}]
      },
      "annotations": {
        "x": 340, "y": 220, "notes": "Devnet only while testing"
      }
    }
  ],
  "edges": [
    {
      "id":"edge_1",
      "from": {"nodeId":"start","port":"program"},
      "to":   {"nodeId":"node_spl_token_mint_1","port":"payer"},
      "type": "data"
    }
  ],
  "start": { "id":"start","network":"devnet","programName":"vestra_program" }
}

PUT /v1/projects/{projectId}/canvas

Replace entire graph (atomic).

PATCH /v1/projects/{projectId}/canvas

Partial update: add/remove nodes/edges, update params.

Operations

{
  "ops": [
    { "op":"addNode", "node":{...} },
    { "op":"updateNode", "id":"node_1", "patch":{ "params.decimals": 6 } },
    { "op":"removeNode", "id":"node_legacy" },
    { "op":"addEdge", "edge":{...} }
  ]
}

POST /v1/projects/{projectId}/canvas/validate

Static checks: schema, missing connections, account constraints, PDA seeds, Anchor IDLs.

Response

{ "valid": true, "warnings": [], "errors": [] }

---

Module Library

GET /v1/modules?category=token|nft|core|governance&query=...

Return available modules with schema.

Module Schema

{
  "type": "splTokenMint",
  "displayName": "SPL Token Mint",
  "category": "token",
  "paramsSchema": {
    "name": {"type":"string","required":true},
    "symbol": {"type":"string","required":true},
    "decimals": {"type":"integer","min":0,"max":9,"default":9},
    "initialSupply": {"type":"string","format":"u64","default":"0"},
    "mintAuthority": {"type":"string","enum":["wallet","pda","custom"],"default":"wallet"},
    "freezeAuthority": {"type":["null","string"],"default":null}
  },
  "inputs": [{"key":"payer","type":"pubkey"}],
  "outputs":[{"key":"mint","type":"pubkey"}],
  "docsUrl": "https://docs.vestralabs.xyz/forge/modules/spl-token-mint"
}

---

Code Generation

POST /v1/projects/{projectId}/generate

Generates code (Anchor workspace + IDL) from the canvas.

Body

{ "language": "rust-anchor", "optLevel": "O1|O2|O3", "includeTests": true }

Response

{
  "jobId": "job_gen_123",
  "artifacts": {
    "idl": "https://…/idl.json",
    "zip": "https://…/vestra_program.zip"
  },
  "status": "queued"
}

GET /v1/jobs/{jobId}

Track generate/compile/deploy jobs (shared status model).

Job Model

{
  "id": "job_gen_123",
  "kind": "generate|compile|deploy",
  "status": "queued|running|succeeded|failed|canceled",
  "progress": 74,
  "logsUrl": "wss://forge.vestralabs.xyz/ws/jobs/job_gen_123",
  "result": { "idlUrl": "...", "binaryUrl": "..." },
  "error": null,
  "startedAt": "2025-09-15T20:31:00Z",
  "endedAt": null
}

---

Build & Compile

POST /v1/projects/{projectId}/compile

Compiles Anchor program; returns job.

Body

{ "network":"devnet", "features":["spl-token-2022"], "rustVersion":"1.79" }

Result Artifacts (so/dylib), size, warnings.

---

Simulation

POST /v1/projects/{projectId}/simulate

Dry-run instructions (no chain writes). Useful for account metas, rent, compute units.

Body

{
  "network": "devnet",
  "instruction": {
    "programId": "vestra1111…",
    "name": "mint_tokens",
    "accounts": {
      "mint": "MintPubkey",
      "authority": "WalletPubkey",
      "tokenAccount": "ATA..."
    },
    "args": { "amount": "1000000000" }
  }
}

Response

{
  "ok": true,
  "computeUnits": 31211,
  "logs": ["Program log: starting mint", "..."],
  "preBalances": {...},
  "postBalances": {...},
  "returnedData": null,
  "rentExempt": false,
  "warnings": []
}

---

Deploy

Security: Requires wallet signature via client; server verifies via X-Wallet-Address + SIWS (Sign-In With Solana) challenge.

POST /v1/projects/{projectId}/deploy

Deploys the compiled program to the selected network.

Body

{
  "network": "devnet",
  "programUpgradeAuthority": "WalletPubkey|PDA",
  "computeBudget": { "units": 1400000, "microLamports": 1 },
  "priorityFeeMicrolamports": 1000
}

Response

{ "jobId": "job_dep_456", "status": "queued" }

On success (job result)

{
  "programId": "vestra1111111111…",
  "txId": "5eVn…",
  "explorerUrl": "https://explorer.solana.com/tx/5eVn…?cluster=devnet",
  "idlUrl": "https://…/idl.json"
}

---

Accounts & IDL

GET /v1/projects/{projectId}/idl

Latest IDL (generated or deployed).

GET /v1/programs/{programId}/accounts?network=devnet&type=Mint|TokenAccount|CustomType&limit=50&cursor=...

Indexed accounts for a deployed program.

POST /v1/programs/{programId}/rpc

Passthrough for selected read-only RPCs (server-side keyed, rate-limited):

{ "network":"devnet", "method":"getProgramAccounts", "params":[ "vestra1111…", { "encoding":"jsonParsed" } ] }

---

Wallets

GET /v1/wallets

Linked wallets (Phantom, Solflare).

POST /v1/wallets/link

Server creates a challenge → client signs → server verifies → link.

DELETE /v1/wallets/{address}

Unlink.

---

WebSockets

• wss://forge.vestralabs.xyz/ws/jobs/{jobId} → live logs & progress

• wss://forge.vestralabs.xyz/ws/project/{projectId} → canvas presence, cursors, locks

Message Envelope

{ "type":"progress|log|done|error", "data":{...}, "timestamp": 1737039000 }

---

Webhooks (Enterprise)

POST /v1/webhooks

Create a webhook to receive events.

Events

• job.succeeded, job.failed

• project.published

• deploy.succeeded, deploy.failed

Delivery

{
  "id":"evt_123",
  "type":"deploy.succeeded",
  "createdAt":"2025-09-15T…Z",
  "data":{ "projectId":"proj_123","programId":"vestra111…","network":"devnet" },
  "signature":"hex-hmac-sha256"
}

---

Errors

Consistent error envelope:

{
  "error": {
    "code": "VALIDATION_ERROR|AUTH_REQUIRED|RATE_LIMIT|RPC_DOWN|COMPILE_FAILED|DEPLOY_FAILED",
    "message": "Human-readable detail",
    "details": { "field": "params.decimals", "issue": "must be <= 9" },
    "traceId": "req_abc123"
  }
}

HTTP codes:

• 400 validation, 401 auth, 403 permission, 404 not found

• 409 conflict, 422 semantic, 429 rate limit

• 5xx internal/RPC upstream

---

Pagination

Query params: page, limit or cursor (opaque).

Envelope

{ "items":[...], "nextCursor": "eyJwYWdlIjoyfQ==" }

---

Rate Limits

• Default: 60 req/min per token.

• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After.

---

Example Workflows

1) Create Token Mint Flow (Devnet)

Create project

curl -H "Authorization: Bearer $TOKEN"   -X POST https://forge.vestralabs.xyz/api/v1/projects   -d '{ "workspaceId":"ws_123","name":"My Token","network":"devnet" }'

Add node + connect

curl -H "Authorization: Bearer $TOKEN"   -X PATCH https://forge.vestralabs.xyz/api/v1/projects/proj_123/canvas   -d '{
    "ops":[
      {"op":"addNode","node":{
        "id":"node_mint","type":"splTokenMint","title":"Token Mint",
        "params":{"name":"Vestra Token","symbol":"VST","decimals":9,"initialSupply":"1000000000000","mintAuthority":"wallet"}
      }},
      {"op":"addEdge","edge":{"id":"e1","from":{"nodeId":"start","port":"program"},"to":{"nodeId":"node_mint","port":"payer"},"type":"data"}}
    ]}'

Validate

curl -H "Authorization: Bearer $TOKEN"   -X POST https://forge.vestralabs.xyz/api/v1/projects/proj_123/canvas/validate

Generate → Compile → Deploy

curl -H "Authorization: Bearer $TOKEN" -X POST https://forge.vestralabs.xyz/api/v1/projects/proj_123/generate
curl -H "Authorization: Bearer $TOKEN" -X POST https://forge.vestralabs.xyz/api/v1/projects/proj_123/compile -d '{ "network":"devnet" }'
curl -H "Authorization: Bearer $TOKEN" -X POST https://forge.vestralabs.xyz/api/v1/projects/proj_123/deploy -d '{ "network":"devnet" }'

Track job

curl -H "Authorization: Bearer $TOKEN" https://forge.vestralabs.xyz/api/v1/jobs/job_dep_456

---

OpenAPI (Starter)

openapi: 3.0.3
info:
  title: Vestra Forge API
  version: 1.0.0
servers:
  - url: https://forge.vestralabs.xyz/api/v1
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /projects:
    get:
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: query; name: workspaceId; schema: { type: string }
        - in: query; name: status; schema: { type: string, enum: [draft,published,archived] }
      responses: { '200': { description: OK } }
    post:
      security: [ { bearerAuth: [] } ]
      responses: { '201': { description: Created } }
  /projects/{projectId}/canvas:
    get: { security: [ { bearerAuth: [] } ], responses: { '200': { description: OK } } }
    put: { security: [ { bearerAuth: [] } ], responses: { '200': { description: Replaced } } }
    patch: { security: [ { bearerAuth: [] } ], responses: { '200': { description: Patched } } }
  /projects/{projectId}/generate:
    post: { security: [ { bearerAuth: [] } ], responses: { '202': { description: Queued } } }
  /projects/{projectId}/compile:
    post: { security: [ { bearerAuth: [] } ], responses: { '202': { description: Queued } } }
  /projects/{projectId}/deploy:
    post: { security: [ { bearerAuth: [] } ], responses: { '202': { description: Queued } } }

---

Security & Compliance

• SIWS (Sign-In With Solana) for wallet auth challenges.

• Per-tenant encryption for stored artifacts and IDLs.

• RPC keys (Helius/Quicknode) kept server-side; no client leakage.

• Strict CORS on write endpoints.

• Build sandboxes with seccomp/AppArmor; no outbound except allow-list (crates.io, Solana RPCs).