FORGE API & WebSocket Contract

Base: /api/v1

Public REST

`GET /health`

Returns service/build/db/redis status. Never expose secrets.

`GET /config/public`

Returns chain ID, supported launch rails, public contract addresses, enabled templates, feature flags safe for client use, and live platformFeeBps, callerTipBps, fee disclosure strings (defaults: 15% of gross platform; 1% of beneficiary pool tip).

`GET /agents`

Query params: cursor, limit, category, status, sort, q.

`GET /agents/:idOrSlug`

Agent profile, token mapping, public capabilities, launch state, metrics, boost status.

`GET /tokens/:chainId/:address`

Normalized token + launch state.

`GET /tokens/:chainId/:address/trades`

Cursor-paginated indexed trades.

`GET /tokens/:chainId/:address/candles`

Params: interval=1m|5m|15m|1h|4h|1d, from, to. Preferred path for UI charts: Mobula-backed TradingView datafeed via /market/ohlcv (Market data). This candles route may proxy Mobula or serve indexer-derived aggregates as a fallback.

Market (Mobula proxy)

Enterprise key stays on the server. Browser calls FORGE only.

`GET /market/ohlcv`

TradingView getBars proxy. Query: chainId, address or asset, mode=pool|asset, from, to, period.

`GET /market/symbols`

Resolve token/pool metadata for the chart symbol.

`GET /market/price`

Optional spot helper for headers/sparklines.

Swap (Mobula proxy)

`POST /swap/quote`

Body: tokenIn, tokenOut, amount or amountRaw, walletAddress, slippageBps, optional poolAddress. Proxies Mobula GET /api/2/swap/quoting (chainId=evm:4663). Returns display amounts + unsigned EVM tx (to/data/value) after allowlisting MobulaRouter. Never returns MOBULA_API_KEY.

`POST /swap/prepare-approval`

Optional helper: ERC-20 spender (MobulaRouter) + amount from a quote id.

`GET /trending`

Organic trending list. Boost inventory is returned separately, never mixed invisibly.

`GET /boosts/placements/:placement`

Active paid placements with sponsored: true.

Authentication

`POST /auth/nonce`

json

{"address":"0x..."}

`POST /auth/verify`

json

{"address":"0x...","message":"...","signature":"0x..."}

Returns/sets secure session.

`POST /auth/logout`

Creator Agent API

`POST /agents`

Create draft.

json

{
  "name":"Luna",
  "ticker":"LUNA",
  "template":"trading",
  "shortDescription":"...",
  "personality":"...",
  "beneficiary":"0x..."
}

`PATCH /agents/:id`

Draft-only editable fields or explicitly mutable runtime settings.

`POST /agents/identity/generate`

Wallet session required. Runs Grok identity generation for a template (Phase A text + Phase B avatar candidates). See Identity generation.

json

{
  "template":"trading",
  "seed":"late-night perps analyst, dry humor, no moonspeak",
  "agentId":"optional-draft-uuid",
  "avatarVariants":3
}

Returns structured identity fields + avatar candidate URLs (FORGE-hosted after download) + usage metadata. Prefer SSE when the client requests Accept: text/event-stream.

`POST /agents/:id/identity/generate`

Same as above, bound to an existing draft Agent owned by the session.

`POST /agents/:id/identity/regenerate-avatar`

Reruns image generation only from the draft’s current name/personality/avatarPrompt + template style pack.

`POST /agents/:id/avatar`

Manual upload path. Returns upload instructions or stores validated image. Restrict MIME/size; strip metadata if appropriate. Does not require xAI.

`POST /agents/:id/launch-simulate`

Read-only simulate / ECA compute. No chain write. Validates Agent completeness, fetches live PONS config, pins salt + economics, predicts CREATE2 addresses.

Request (optional overrides):

json

{
  "launchConfigId":"0",
  "pairToken":"0x0000000000000000000000000000000000000000",
  "creatorTaxBps":0,
  "buybackEnabled":false,
  "initialBuy":"0",
  "salt":"0x...optional; server generates if omitted"
}

Response:

json

{
  "simulationId":"uuid",
  "adapter":"pons",
  "chainId":4663,
  "expiresAt":"...",
  "salt":"0x...",
  "expectedEconomics":"0x...",
  "ecas":{
    "vault":"0x...",
    "token":"0x...",
    "curve":"0x..."
  },
  "beneficiary":"0x...",
  "creatorFeeRecipient":"0x...",
  "canLaunch":true,
  "display":{
    "launchFee":"...",
    "pairAsset":"ETH",
    "platformFeeOnCreatorProceeds":"15%",
    "claimCallerTipOnBeneficiaryShare":"1%",
    "initialBuy":"0"
  }
}

UI must call this from a Compute addresses button and show all three ECAs before enabling Launch.

`POST /agents/:id/launch-intent`

Requires a valid unexpired simulationId from launch-simulate. Returns one unsigned tx to ForgeLaunchRouter that deploys the vault and launches the token in the same call. Does not pre-deploy the vault in a separate server/user tx.

Example:

json

{
  "simulationId":"uuid",
  "adapter":"pons",
  "chainId":4663,
  "to":"0xForgeLaunchRouter",
  "data":"0x...",
  "value":"500000000000000",
  "creatorFeeRecipient":"0xAgentVaultECA",
  "ecas":{
    "vault":"0x...",
    "token":"0x...",
    "curve":"0x..."
  },
  "economicsHash":"0x...",
  "expiresAt":"...",
  "display":{
    "launchFee":"...",
    "pairAsset":"ETH",
    "platformFeeOnCreatorProceeds":"15%",
    "claimCallerTipOnBeneficiaryShare":"1%"
  }
}

`POST /agents/:id/launch-submitted`

Client sends tx hash after wallet submission. Backend does not mark live until chain indexer confirms vault + token from that tx.

`GET /agents/:id/usage`

Creator-only model/compute usage.

Chat

`POST /agents/:id/chat/sessions`

Creates session.

`POST /agents/:id/chat/sessions/:sessionId/messages`

Use SSE or chunked streaming for model tokens; WebSocket remains for product/chain events.

Input:

json

{"content":"Analyze the latest on-chain activity."}

Server events:

text

event: response.start
event: response.delta
event: tool.start
event: tool.end
event: response.completed
event: error

`DELETE /agents/:id/chat/sessions/:sessionId`

Deletes user-visible session where retention policy permits.

Fee API

`GET /agents/:id/fees`

Indexed claim/split history, current on-chain claimable estimate, vault owner, current beneficiary.

`POST /agents/:id/fees/claim`

Returns an unsigned permissionless claimAndSplit* tx the caller can sign (they earn callerTipBps of the post-platform beneficiary pool, default 1% — not from platform), and/or enqueues the FORGE keeper to evaluate profitability. Do not require the caller to be the beneficiary. Keeper may skip if tip < gas + min profit (Fee keeper).

`POST /agents/:id/fees/set-beneficiary`

Creator session must match vault owner. Body: { "beneficiary": "0x..." }. Returns unsigned AgentFeeVault.setBeneficiary tx. Index BeneficiaryUpdated before updating DB cache.

`POST /agents/:id/fees/transfer-ownership`

Creator session must match vault owner. Body: { "newOwner": "0x..." }. Returns unsigned transferOwnership tx.

Admin

All admin endpoints require admin session + audit log.

POST /admin/agents/:id/verify
POST /admin/agents/:id/chat-disable
POST /admin/feature-flags
POST /admin/indexer/backfill
POST /admin/indexer/replay-block
POST /admin/platform-token/register
POST /admin/boosts/reconcile
POST /admin/fees/platform-bps — on-chain setPlatformFeeBps (or admin-signed relay). Body: { "bps": 1500 }. Cap 3000. Audit log required.
POST /admin/fees/caller-tip-bps — on-chain setCallerTipBps. Body: { "bps": 100 }. Cap 500. Audit log required.

WebSocket

Endpoint: /ws

Client -> server:

json

{"op":"subscribe","channel":"token:4663:0xabc...","cursor":"optional"}

Allowed channels:

global
agent:{uuid}
token:{chainId}:{address}
launches

Server event:

json

{
  "v":1,
  "seq":"18492381-00012",
  "type":"trade.executed",
  "channel":"token:4663:0x...",
  "ts":"...",
  "data":{}
}

Event types:

launch.created
launch.status
trade.executed
market.metrics
fee.split
boost.activated
boost.expired
agent.updated
chain.reorg

Recovery

Client stores last seq. On reconnect it sends cursor. WS service replays from a bounded Redis stream or tells client resync_required, after which client refreshes canonical REST state.

FORGE API & WebSocket Contract

Base: /api/v1

Public REST

`GET /health`

Returns service/build/db/redis status. Never expose secrets.

`GET /config/public`

`GET /agents`

Query params: cursor, limit, category, status, sort, q.

`GET /agents/:idOrSlug`

Agent profile, token mapping, public capabilities, launch state, metrics, boost status.

`GET /tokens/:chainId/:address`

Normalized token + launch state.

`GET /tokens/:chainId/:address/trades`

Cursor-paginated indexed trades.

`GET /tokens/:chainId/:address/candles`

Market (Mobula proxy)

Enterprise key stays on the server. Browser calls FORGE only.

`GET /market/ohlcv`

TradingView getBars proxy. Query: chainId, address or asset, mode=pool|asset, from, to, period.

`GET /market/symbols`

Resolve token/pool metadata for the chart symbol.

`GET /market/price`

Optional spot helper for headers/sparklines.

Swap (Mobula proxy)

`POST /swap/quote`

`POST /swap/prepare-approval`

Optional helper: ERC-20 spender (MobulaRouter) + amount from a quote id.

`GET /trending`

Organic trending list. Boost inventory is returned separately, never mixed invisibly.

`GET /boosts/placements/:placement`

Active paid placements with sponsored: true.

Authentication

`POST /auth/nonce`

json

{"address":"0x..."}

`POST /auth/verify`

json

{"address":"0x...","message":"...","signature":"0x..."}

Returns/sets secure session.

`POST /auth/logout`

Creator Agent API

`POST /agents`

Create draft.

json

{
  "name":"Luna",
  "ticker":"LUNA",
  "template":"trading",
  "shortDescription":"...",
  "personality":"...",
  "beneficiary":"0x..."
}

`PATCH /agents/:id`

Draft-only editable fields or explicitly mutable runtime settings.

`POST /agents/identity/generate`

Wallet session required. Runs Grok identity generation for a template (Phase A text + Phase B avatar candidates). See Identity generation.

json

{
  "template":"trading",
  "seed":"late-night perps analyst, dry humor, no moonspeak",
  "agentId":"optional-draft-uuid",
  "avatarVariants":3
}

Returns structured identity fields + avatar candidate URLs (FORGE-hosted after download) + usage metadata. Prefer SSE when the client requests Accept: text/event-stream.

`POST /agents/:id/identity/generate`

Same as above, bound to an existing draft Agent owned by the session.

`POST /agents/:id/identity/regenerate-avatar`

Reruns image generation only from the draft’s current name/personality/avatarPrompt + template style pack.

`POST /agents/:id/avatar`

Manual upload path. Returns upload instructions or stores validated image. Restrict MIME/size; strip metadata if appropriate. Does not require xAI.

`POST /agents/:id/launch-simulate`

Read-only simulate / ECA compute. No chain write. Validates Agent completeness, fetches live PONS config, pins salt + economics, predicts CREATE2 addresses.

Request (optional overrides):

json

{
  "launchConfigId":"0",
  "pairToken":"0x0000000000000000000000000000000000000000",
  "creatorTaxBps":0,
  "buybackEnabled":false,
  "initialBuy":"0",
  "salt":"0x...optional; server generates if omitted"
}

Response:

json

{
  "simulationId":"uuid",
  "adapter":"pons",
  "chainId":4663,
  "expiresAt":"...",
  "salt":"0x...",
  "expectedEconomics":"0x...",
  "ecas":{
    "vault":"0x...",
    "token":"0x...",
    "curve":"0x..."
  },
  "beneficiary":"0x...",
  "creatorFeeRecipient":"0x...",
  "canLaunch":true,
  "display":{
    "launchFee":"...",
    "pairAsset":"ETH",
    "platformFeeOnCreatorProceeds":"15%",
    "claimCallerTipOnBeneficiaryShare":"1%",
    "initialBuy":"0"
  }
}

UI must call this from a Compute addresses button and show all three ECAs before enabling Launch.

`POST /agents/:id/launch-intent`

Example:

json

{
  "simulationId":"uuid",
  "adapter":"pons",
  "chainId":4663,
  "to":"0xForgeLaunchRouter",
  "data":"0x...",
  "value":"500000000000000",
  "creatorFeeRecipient":"0xAgentVaultECA",
  "ecas":{
    "vault":"0x...",
    "token":"0x...",
    "curve":"0x..."
  },
  "economicsHash":"0x...",
  "expiresAt":"...",
  "display":{
    "launchFee":"...",
    "pairAsset":"ETH",
    "platformFeeOnCreatorProceeds":"15%",
    "claimCallerTipOnBeneficiaryShare":"1%"
  }
}

`POST /agents/:id/launch-submitted`

Client sends tx hash after wallet submission. Backend does not mark live until chain indexer confirms vault + token from that tx.

`GET /agents/:id/usage`

Creator-only model/compute usage.

Chat

`POST /agents/:id/chat/sessions`

Creates session.

`POST /agents/:id/chat/sessions/:sessionId/messages`

Use SSE or chunked streaming for model tokens; WebSocket remains for product/chain events.

Input:

json

{"content":"Analyze the latest on-chain activity."}

Server events:

text

event: response.start
event: response.delta
event: tool.start
event: tool.end
event: response.completed
event: error

`DELETE /agents/:id/chat/sessions/:sessionId`

Deletes user-visible session where retention policy permits.

Fee API

`GET /agents/:id/fees`

Indexed claim/split history, current on-chain claimable estimate, vault owner, current beneficiary.

`POST /agents/:id/fees/claim`

`POST /agents/:id/fees/set-beneficiary`

Creator session must match vault owner. Body: { "beneficiary": "0x..." }. Returns unsigned AgentFeeVault.setBeneficiary tx. Index BeneficiaryUpdated before updating DB cache.

`POST /agents/:id/fees/transfer-ownership`

Creator session must match vault owner. Body: { "newOwner": "0x..." }. Returns unsigned transferOwnership tx.

Admin

All admin endpoints require admin session + audit log.

POST /admin/agents/:id/verify
POST /admin/agents/:id/chat-disable
POST /admin/feature-flags
POST /admin/indexer/backfill
POST /admin/indexer/replay-block
POST /admin/platform-token/register
POST /admin/boosts/reconcile
POST /admin/fees/platform-bps — on-chain setPlatformFeeBps (or admin-signed relay). Body: { "bps": 1500 }. Cap 3000. Audit log required.
POST /admin/fees/caller-tip-bps — on-chain setCallerTipBps. Body: { "bps": 100 }. Cap 500. Audit log required.

WebSocket

Endpoint: /ws

Client -> server:

json

{"op":"subscribe","channel":"token:4663:0xabc...","cursor":"optional"}

Allowed channels:

global
agent:{uuid}
token:{chainId}:{address}
launches

Server event:

json

{
  "v":1,
  "seq":"18492381-00012",
  "type":"trade.executed",
  "channel":"token:4663:0x...",
  "ts":"...",
  "data":{}
}

Event types:

launch.created
launch.status
trade.executed
market.metrics
fee.split
boost.activated
boost.expired
agent.updated
chain.reorg

Recovery

Client stores last seq. On reconnect it sends cursor. WS service replays from a bounded Redis stream or tells client resync_required, after which client refreshes canonical REST state.