SignalArc REST API

Live production API base URL:

https://api.signalarc.fun

For local development, use http://localhost:4000. Local-only references such as ngrok tunnels are development conveniences, not production endpoints. The production API is live on GCP Cloud Run service signalarc-backend-api behind the custom domain api.signalarc.fun. Agent execution is backend-managed; the current production direction is Circle Developer-Controlled Wallet API or direct Circle API integration, not a production dependency on Circle CLI. Phase 6 deployment requires the production database to be migrated through schema version 20 before the Agent API durable intent, execution, portfolio, and activity surfaces are considered current.

API Status

Item	Status
Production API	Live at `https://api.signalarc.fun`.
Local API	Implemented by the Go backend on `http://localhost:4000`.
Authentication	Not enforced.
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	Production frontend `https://signalarc.fun` is allowed. Local frontend origins are also allowed in development.

Agent API

SignalArc exposes a framework-neutral Agent API for external agents and custom HTTP clients. Keep this page as the general REST API reference; use Agent API for the full agent integration guide, required fields, lifecycle examples, error catalog, and local smoke-test evidence. Agent execution status:

Agent execution is backend-managed.
Current target execution path is Circle Developer-Controlled Wallet API or direct Circle API integration.
Local Docker smoke testing validated circle_developer_wallet_api mode for the documented ARC-TESTNET lifecycle actions.
Agent execution is currently scoped to ARC-TESTNET.
Backend wallet provider configuration is required before execution endpoints can broadcast.
API responses do not return Circle API keys, entity secrets, entitySecretCiphertext, database URLs, deploy tokens, credential paths, or other backend secrets.

Error Format

Errors use a consistent JSON envelope:

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

Endpoint Table

Core REST endpoints:

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.

Agent endpoints (live, see Agent API for the full reference):

Method	Path	Purpose
POST	`/agent/onboarding/start`	Start agent onboarding and dispatch OTP email.
POST	`/agent/onboarding/verify`	Verify OTP, register agent wallet, and activate session.
GET	`/agent/onboarding/{onboarding_id}`	Get onboarding status.
GET	`/agent/sessions/{agent_id}`	Get active agent session.
POST	`/agent/wallets`	Register or upsert an agent wallet record.
GET	`/agent/wallets/{agent_id}`	Get registered agent wallet.
GET	`/agent/wallets/{agent_id}/balance`	Read-only Circle Agent Wallet balance.
POST	`/agent/wallets/{agent_id}/faucet`	Request ARC-TESTNET faucet funding for the registered agent wallet.
POST	`/agent/wallets/{agent_id}/disable`	Disable a registered agent wallet.
POST	`/agent/intents`	Create an agent intent preview.
GET	`/agent/intents/{intent_id}`	Get the current durable intent state.
POST	`/agent/intents/{intent_id}/confirm`	Confirm an agent intent.
POST	`/agent/intents/{intent_id}/execute`	Execute a confirmed agent intent.
GET	`/agent/intents/{intent_id}/executions`	List durable execution attempts for an intent.
GET	`/agent/portfolio/{agent_id}`	Read agent portfolio summary derived from durable agent records.
GET	`/agent/activity/{agent_id}`	Read agent activity/history derived from durable agent records.

Common Response Shapes

Market

{
  "id": "uuid",
  "creator_user_id": "uuid",
  "title": "Market title",
  "description": null,
  "category": null,
  "cover_image_url": "https://example.com/market-cover.png",
  "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": 20,
  "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,
    "cover_image_url": 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",
    "cover_image_url": "https://example.com/market-cover.png",
    "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.
`cover_image_url`	No	Public HTTPS URL, maximum 2048 characters. 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. Market images are URL metadata only in v1. SignalArc does not accept base64 image data or store uploaded images on the Cloud Run filesystem. A later upload flow can use signed upload URLs backed by GCS or Cloudinary. 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. The frontend trade panel 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 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.

Agent Endpoints

The Agent API surface is documented in detail in Agent API, which is the canonical framework-neutral reference and can be shared with external agents, agent frameworks, and custom HTTP clients. It covers onboarding, OTP verify, sessions, wallets, balance, ARC-TESTNET faucet, market discovery, durable intent preview/confirm/execute, durable execution records, intent execution history, portfolio, activity, idempotency through agent_id + source_client + client_request_id, and Phase 6 safety/policy checks such as agent_id validation, allowed_actions, explicit confirmation, and optional policy_metadata.max_trade_amount. The Custom GPT shipped with SignalArc is preconfigured against https://api.signalarc.fun, but the Agent API contract is not Custom GPT-specific.

​SignalArc REST API

​API Status

​Agent API

​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

​Agent Endpoints

SignalArc REST API

API Status

Agent API

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

Agent Endpoints