SignalArc REST API

Primary planned API base URL:

https://api.signalarc.fun

For local development, use http://localhost:4000. The API is currently a local/testnet implementation. The planned production API domain is documented for deployment planning, but live production deployment and DNS are not completed.

API Status

Item	Status
Production API	Planned at `https://api.signalarc.fun`; not live yet.
Local API	Implemented by the Go backend.
Authentication	Not implemented.
API keys	Schema exists, but request enforcement is not implemented.
Content type	`application/json`.
Request ID	`X-Request-ID` is echoed when supplied or generated by middleware.
CORS	Local frontend origins only in current backend code.

Error Format

Errors use a consistent JSON envelope:

{
  "error": {
    "code": "invalid_trade_intent",
    "message": "invalid trade intent"
  }
}

Endpoint Table

Method	Path	Purpose
GET	`/health`	Process health check.
GET	`/readyz`	Database readiness check.
GET	`/schema/validate`	Validate expected schema and migration state.
GET	`/markets`	List markets.
GET	`/markets/{id}`	Get one market.
POST	`/markets`	Create a market record.
POST	`/trade-intents`	Create a backend trade intent record; does not execute onchain.
GET	`/agent/markets`	Agent-readable market list.
GET	`/users/{user_id}/positions`	List positions for a user.
GET	`/markets/{market_id}/positions`	List positions for a market.
GET	`/markets/{market_id}/resolution`	Get one market resolution.
GET	`/users/{user_id}/settlements`	List settlements for a user.
GET	`/markets/{market_id}/settlements`	List settlements for a market.
GET	`/arc/contract`	Return Arc Testnet contract metadata.

Common Response Shapes

Market

{
  "id": "uuid",
  "creator_user_id": "uuid",
  "title": "Market title",
  "description": null,
  "category": null,
  "status": "OPEN",
  "outcome_yes_label": "YES",
  "outcome_no_label": "NO",
  "collateral_asset": "USDC",
  "chain": "Arc Testnet",
  "resolution_source": null,
  "opens_at": null,
  "closes_at": "2026-06-01T00:00:00Z",
  "resolved_at": null,
  "settled_at": null,
  "winning_outcome": null,
  "created_at": "2026-05-20T00:00:00Z",
  "updated_at": "2026-05-20T00:00:00Z"
}

Trade

{
  "id": "uuid",
  "user_id": "uuid",
  "market_id": "uuid",
  "outcome": "YES",
  "side": "BUY",
  "quantity": "10",
  "price": "0.5",
  "collateral_amount": "5",
  "fee_amount": "0",
  "status": "PENDING",
  "tx_hash": null,
  "created_at": "2026-05-20T00:00:00Z",
  "updated_at": "2026-05-20T00:00:00Z"
}

Endpoints

GET /health

Returns process health.

curl https://api.signalarc.fun/health

Success status: 200 OK Response:

{"status":"ok"}

Known errors: none from handler logic.

GET /readyz

Checks database reachability.

curl https://api.signalarc.fun/readyz

Success status: 200 OK Response:

{"status":"ok"}

Known errors:

Status	Code	Meaning
503	`database_unavailable`	Database ping failed.

GET /schema/validate

Validates expected database tables and migration state.

curl https://api.signalarc.fun/schema/validate

Success status: 200 OK when schema status is ok. Response:

{
  "status": "ok",
  "migration_version": 13,
  "dirty": false,
  "missing_tables": []
}

Known errors:

Status	Code	Meaning
500	`schema_validation_failed`	Schema validation query failed.
503	n/a	Returned when validation result status is not `ok`.

GET /markets

Lists up to 50 markets ordered by creation time descending.

curl https://api.signalarc.fun/markets

Success status: 200 OK Response:

{
  "markets": []
}

Known errors:

Status	Code	Meaning
500	`markets_list_failed`	Market list query failed.

GET /markets/

Returns one market by UUID.

curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003

Success status: 200 OK Response:

{
  "market": {
    "id": "10000000-0000-4000-8000-000000000003",
    "creator_user_id": "10000000-0000-4000-8000-000000000001",
    "title": "Example market",
    "description": null,
    "category": null,
    "status": "OPEN",
    "outcome_yes_label": "YES",
    "outcome_no_label": "NO",
    "collateral_asset": "USDC",
    "chain": "Arc Testnet",
    "resolution_source": null,
    "opens_at": null,
    "closes_at": "2026-06-01T00:00:00Z",
    "resolved_at": null,
    "settled_at": null,
    "winning_outcome": null,
    "created_at": "2026-05-20T00:00:00Z",
    "updated_at": "2026-05-20T00:00:00Z"
  }
}

Known errors:

Status	Code	Meaning
404	`market_not_found`	No market exists for the supplied id.
500	`market_get_failed`	Market query failed.

POST /markets

Creates a market record. Server-owned lifecycle fields are rejected.

curl -X POST https://api.signalarc.fun/markets \
  -H "Content-Type: application/json" \
  -d '{
    "creator_user_id": "10000000-0000-4000-8000-000000000001",
    "title": "Will SignalArc complete its public docs?",
    "description": "Public documentation readiness market.",
    "category": "product",
    "outcome_yes_label": "YES",
    "outcome_no_label": "NO",
    "collateral_asset": "USDC",
    "chain": "Arc Testnet",
    "resolution_source": "Project repository evidence",
    "closes_at": "2026-06-01T00:00:00Z"
  }'

Request fields:

Field	Required	Notes
`creator_user_id`	Yes	UUID-shaped string. Must reference an existing user.
`title`	Yes	Non-empty string.
`description`	No	Optional string. Empty string becomes null.
`category`	No	Optional string. Empty string becomes null.
`outcome_yes_label`	No	Defaults to `YES`.
`outcome_no_label`	No	Defaults to `NO`.
`collateral_asset`	No	Defaults to `USDC`.
`chain`	Yes	Non-empty string.
`resolution_source`	No	Optional string. Empty string becomes null.
`opens_at`	No	RFC3339 timestamp. Must be before `closes_at`. Future `opens_at` creates `DRAFT`; otherwise status is `OPEN`.
`closes_at`	Yes	RFC3339 timestamp in the future.

Rejected fields: status, winning_outcome, resolved_at, settled_at. Success status: 201 Created Response:

{
  "market": {
    "id": "uuid",
    "status": "OPEN"
  }
}

Known errors:

Status	Code	Meaning
400	`invalid_json`	Request body is not valid JSON.
400	`invalid_market_request`	Validation failed or server-owned lifecycle fields were included.
400	`invalid_creator_user`	Creator user foreign key is invalid.
500	`market_create_failed`	Insert failed.

POST /trade-intents

Creates a backend trade-intent record. This endpoint is not the primary onchain execution path in the current working tree. The frontend trade panel currently uses the browser wallet to send Arc Testnet approve and openPosition transactions directly. The backend response explicitly marks execution as not_executed.

curl -X POST https://api.signalarc.fun/trade-intents \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "10000000-0000-4000-8000-000000000001",
    "market_id": "10000000-0000-4000-8000-000000000003",
    "outcome": "YES",
    "side": "BUY",
    "quantity": "10",
    "price": "0.5"
  }'

Request fields:

Field	Required	Notes
`user_id`	Yes	UUID-shaped string.
`market_id`	Yes	UUID-shaped string.
`outcome`	Yes	`YES` or `NO`.
`side`	Yes	`BUY` or `SELL`.
`quantity`	Yes	Positive decimal with at most 18 fractional digits and at most 18 significant integer digits.
`price`	Yes	Decimal between `0` and `1`, with the same decimal bounds.

Success status: 201 Created Response:

{
  "trade": {
    "id": "uuid",
    "status": "PENDING",
    "tx_hash": null
  },
  "execution": {
    "status": "not_executed",
    "reason": "onchain execution is not implemented in Phase 3 backend MVP"
  }
}

Known errors:

Status	Code	Meaning
400	`invalid_json`	Request body is not valid JSON.
400	`invalid_trade_intent`	Request validation failed.
400	`market_not_open`	Market exists but status is not `OPEN`.
404	`market_not_found`	Market does not exist.
500	`trade_intent_create_failed`	Lookup or insert failed.

GET /agent/markets

Returns a compact market list for agent-readable discovery and dashboards.

curl https://api.signalarc.fun/agent/markets

Success status: 200 OK Response:

{
  "markets": [
    {
      "id": "uuid",
      "title": "Example market",
      "status": "OPEN",
      "category": "product",
      "collateral_asset": "USDC",
      "chain": "Arc Testnet",
      "closes_at": "2026-06-01T00:00:00Z",
      "resolution_source": "Project repository evidence"
    }
  ]
}

Known errors:

Status	Code	Meaning
500	`markets_list_failed`	Market list query failed.

GET /users//positions

Lists up to 50 positions for a user.

curl https://api.signalarc.fun/users/10000000-0000-4000-8000-000000000001/positions

Success status: 200 OK Response:

{
  "positions": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "market_id": "uuid",
      "outcome": "YES",
      "quantity": "10",
      "average_entry_price": "0.5",
      "realized_pnl": "0",
      "created_at": "2026-05-20T00:00:00Z",
      "updated_at": "2026-05-20T00:00:00Z"
    }
  ]
}

Known errors: 500 positions_list_failed.

GET /markets//positions

Lists up to 50 positions for a market.

curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003/positions

Success status: 200 OK Known errors: 500 positions_list_failed.

GET /markets//resolution

Returns a market resolution record.

curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003/resolution

Success status: 200 OK Response:

{
  "resolution": {
    "id": "uuid",
    "market_id": "uuid",
    "winning_outcome": "YES",
    "status": "RESOLVED",
    "resolver_type": "manual",
    "evidence_reference": "Evidence URL or note",
    "resolved_at": "2026-05-20T00:00:00Z",
    "created_at": "2026-05-20T00:00:00Z",
    "updated_at": "2026-05-20T00:00:00Z"
  }
}

Known errors:

Status	Code	Meaning
404	`resolution_not_found`	No resolution exists for this market.
500	`resolution_get_failed`	Resolution query failed.

GET /users//settlements

Lists up to 50 settlements for a user.

curl https://api.signalarc.fun/users/10000000-0000-4000-8000-000000000001/settlements

Success status: 200 OK Known errors: 500 settlements_list_failed.

GET /markets//settlements

Lists up to 50 settlements for a market.

curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003/settlements

Success status: 200 OK Response shape:

{
  "settlements": [
    {
      "id": "uuid",
      "market_id": "uuid",
      "user_id": "uuid",
      "resolution_id": "uuid",
      "outcome": "YES",
      "amount": "10",
      "status": "PENDING",
      "tx_hash": null,
      "settled_at": null,
      "created_at": "2026-05-20T00:00:00Z",
      "updated_at": "2026-05-20T00:00:00Z"
    }
  ]
}

Known errors: 500 settlements_list_failed.

GET /arc/contract

Returns the Arc Testnet prototype contract metadata used by the current local MVP.

curl https://api.signalarc.fun/arc/contract

For local development, use http://localhost:4000:

curl http://localhost:4000/arc/contract

Success status: 200 OK Response:

{
  "network": "Arc Testnet",
  "chain_id": 5042002,
  "signal_arc_market": "0xf4ccc11A9e24fb996679F946C23C04AFd2797F26",
  "usdc_erc20_interface": "0x3600000000000000000000000000000000000000",
  "explorer": "https://testnet.arcscan.app",
  "prototype": true,
  "production_approved": false,
  "status": "prototype_testnet_reference"
}

Known errors: none from handler logic.

Overview

API and Agents

Arc and Wallet

Deployment and Security

API

SignalArc REST API

API Status

Error Format

Endpoint Table

Common Response Shapes

Market

Trade

Endpoints

GET /health

GET /readyz

GET /schema/validate

GET /markets

GET /markets/

POST /markets

POST /trade-intents

GET /agent/markets

GET /users//positions

GET /markets//positions

GET /markets//resolution

GET /users//settlements

GET /markets//settlements

GET /arc/contract

Overview

API and Agents

Arc and Wallet

Deployment and Security

Documentation Index

​SignalArc REST API

​API Status

​Error Format

​Endpoint Table

​Common Response Shapes

​Market

​Trade

​Endpoints

​GET /health

​GET /readyz

​GET /schema/validate

​GET /markets

​GET /markets/

​POST /markets

​POST /trade-intents

​GET /agent/markets

​GET /users//positions

​GET /markets//positions

​GET /markets//resolution

​GET /users//settlements

​GET /markets//settlements

​GET /arc/contract

SignalArc REST API

API Status

Error Format

Endpoint Table

Common Response Shapes

Market

Trade

Endpoints

GET /health

GET /readyz

GET /schema/validate

GET /markets

GET /markets/

POST /markets

POST /trade-intents

GET /agent/markets

GET /users//positions

GET /markets//positions

GET /markets//resolution

GET /users//settlements

GET /markets//settlements

GET /arc/contract