> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalarc.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# API

# SignalArc REST API

Live production API base URL:

```text theme={null}
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](./AGENT_API.md) 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:

```json theme={null}
{
  "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](./AGENT_API.md) 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```bash theme={null}
curl https://api.signalarc.fun/health
```

Success status: `200 OK`

Response:

```json theme={null}
{"status":"ok"}
```

Known errors: none from handler logic.

### GET /readyz

Checks database reachability.

```bash theme={null}
curl https://api.signalarc.fun/readyz
```

Success status: `200 OK`

Response:

```json theme={null}
{"status":"ok"}
```

Known errors:

| Status | Code                   | Meaning               |
| ------ | ---------------------- | --------------------- |
| 503    | `database_unavailable` | Database ping failed. |

### GET /schema/validate

Validates expected database tables and migration state.

```bash theme={null}
curl https://api.signalarc.fun/schema/validate
```

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

Response:

```json theme={null}
{
  "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.

```bash theme={null}
curl https://api.signalarc.fun/markets
```

Success status: `200 OK`

Response:

```json theme={null}
{
  "markets": []
}
```

Known errors:

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

### GET /markets/{id}

Returns one market by UUID.

```bash theme={null}
curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003
```

Success status: `200 OK`

Response:

```json theme={null}
{
  "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.

```bash theme={null}
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:

```json theme={null}
{
  "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`.

```bash theme={null}
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:

```json theme={null}
{
  "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.

```bash theme={null}
curl https://api.signalarc.fun/agent/markets
```

Success status: `200 OK`

Response:

```json theme={null}
{
  "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/{user_id}/positions

Lists up to 50 positions for a user.

```bash theme={null}
curl https://api.signalarc.fun/users/10000000-0000-4000-8000-000000000001/positions
```

Success status: `200 OK`

Response:

```json theme={null}
{
  "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/{market_id}/positions

Lists up to 50 positions for a market.

```bash theme={null}
curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003/positions
```

Success status: `200 OK`

Known errors: `500 positions_list_failed`.

### GET /markets/{market_id}/resolution

Returns a market resolution record.

```bash theme={null}
curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003/resolution
```

Success status: `200 OK`

Response:

```json theme={null}
{
  "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/{user_id}/settlements

Lists up to 50 settlements for a user.

```bash theme={null}
curl https://api.signalarc.fun/users/10000000-0000-4000-8000-000000000001/settlements
```

Success status: `200 OK`

Known errors: `500 settlements_list_failed`.

### GET /markets/{market_id}/settlements

Lists up to 50 settlements for a market.

```bash theme={null}
curl https://api.signalarc.fun/markets/10000000-0000-4000-8000-000000000003/settlements
```

Success status: `200 OK`

Response shape:

```json theme={null}
{
  "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.

```bash theme={null}
curl https://api.signalarc.fun/arc/contract
```

For local development, use [http://localhost:4000](http://localhost:4000):

```bash theme={null}
curl http://localhost:4000/arc/contract
```

Success status: `200 OK`

Response:

```json theme={null}
{
  "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](./AGENT_API.md), 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.