> For the complete documentation index, see [llms.txt](https://docs.cournot.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cournot.ai/docs-kr/api-reference/partner-public-api.md).

# 파트너 공개 API

Cournot은 파트너에게 마켓 판정을 조회하고 이의를 제기할 수 있는 공개 엔드포인트를 제공합니다. 시스템은 판정, 신뢰도 평가, 블록체인 증명을 포함한 최종 정산 기록을 생성합니다.

### 기본 URL

> <https://interface.cournot.ai>

#### 응답 엔벨로프(response envelope)

모든 응답은 HTTP 200을 반환합니다. HTTP 상태가 아니라 `code` 필드를 기준으로 분기 처리해야 합니다.

```json
// 성공
{ "code": 0, "msg": "Success", "data": { /* payload */ } }

// 오류
{ "code": 4100, "msg": "slug is required", "detail": "slug is required" }
```

<table data-header-hidden><thead><tr><th width="158.44140625" align="center"></th><th width="107.1875" align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><strong>필드</strong></td><td align="center"><strong>타입</strong></td><td align="center"><strong>설명</strong></td></tr><tr><td align="center"><pre><code>code
</code></pre></td><td align="center">int</td><td align="center">0 = 성공, 0이 아닌 값 = 오류</td></tr><tr><td align="center"><pre><code>msg
</code></pre></td><td align="center">string</td><td align="center">사람이 읽을 수 있는 상태</td></tr><tr><td align="center"><pre><code>data
</code></pre></td><td align="center">object</td><td align="center">성공 시 포함</td></tr><tr><td align="center"><pre><code>detail
</code></pre></td><td align="center">string</td><td align="center">오류 시 포함</td></tr></tbody></table>

### GET `/cournot/markets/public`

마켓의 공개 정산 기록을 조회합니다. 인증이 필요하지 않습니다.

**쿼리 파라미터**:

<table data-header-hidden><thead><tr><th width="139.34765625" align="center"></th><th width="142.44140625" align="center"></th><th width="137.65625" align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center">파라미터</td><td align="center">타입</td><td align="center">필수</td><td align="center">설명</td></tr><tr><td align="center"><code>slug</code></td><td align="center">string</td><td align="center">예</td><td align="center">마켓 슬러그(slug), 앞뒤 슬래시 없음</td></tr><tr><td align="center"><code>source</code></td><td align="center">string</td><td align="center">예</td><td align="center">Cournot이 발급한 파트너별 식별자</td></tr></tbody></table>

#### 요청 예시:

```json
curl -G "https://interface.cournot.ai/cournot/markets/public" \
  --data-urlencode "slug=ram-average-price-above-600-by-end-of-march" \
  --data-urlencode "source=YOUR_SOURCE_ID"
```

#### 응답 예시:

```json
{
  "code": 0,
  "msg": "Success",
  "data": {
    "markets": [
      {
        "id": 61,
        "source": "YOUR_SOURCE_ID",
        "slug": "ram-average-price-above-600-by-end-of-march",
        "status": "resolved",
        "verdict": "YES",
        "resolved_at": "2026-04-28T10:08:40Z",
        "confidence": "HIGH",
        "reasoning": "multi-source evidence confirmed the final outcome is YES",
        "proofs": [
          { "chain": "base", "tx_hash": "0xabc..." },
          { "chain": "bsc", "tx_hash": "0xdef..." }
        ],
        "disputes": [
          {
            "id": 4,
            "status": "closed",
            "submitter_selection": "NO",
            "reason_text": "we believe the resolved outcome is incorrect",
            "submitted_at": "2026-04-28T10:30:00Z",
            "decision": {
              "type": "override",
              "partner_final_verdict": "NO",
              "reason_text": "submitted dispute is valid",
              "decided_at": "2026-04-28T11:00:00Z"
            }
          }
        ]
      }
    ]
  }
}
```

#### 응답 필드(`data.markets[]`):

<table data-header-hidden><thead><tr><th width="147.43359375" align="center"></th><th width="140.875" align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><strong>필드</strong></td><td align="center"><strong>타입</strong></td><td align="center"><strong>설명</strong></td></tr><tr><td align="center"><code>id</code></td><td align="center">int64</td><td align="center">마켓 식별자</td></tr><tr><td align="center"><code>source</code></td><td align="center">string</td><td align="center">파트너 source 식별자</td></tr><tr><td align="center"><code>slug</code></td><td align="center">string</td><td align="center">마켓 슬러그</td></tr><tr><td align="center"><code>status</code></td><td align="center">string</td><td align="center"><code>monitoring</code>(모니터링 중) / <code>resolved</code>(결과 확정) / <code>disputed</code>(이의 제기됨) / <code>closed</code>(종료)</td></tr><tr><td align="center"><code>verdict</code></td><td align="center">string</td><td align="center">최종 판정 텍스트</td></tr><tr><td align="center"><code>resolved_at</code></td><td align="center">string</td><td align="center">RFC 3339 UTC 타임스탬프</td></tr><tr><td align="center"><code>confidence</code></td><td align="center">string</td><td align="center"><code>VERY_HIGH</code>(매우 높음) / <code>HIGH</code>(높음) / <code>MEDIUM</code>(보통) / <code>LOW</code>(낮음) / <code>VERY_LOW</code>(매우 낮음)</td></tr><tr><td align="center"><code>reasoning</code></td><td align="center">string</td><td align="center">사람이 읽을 수 있는 설명</td></tr><tr><td align="center"><code>proofs</code></td><td align="center">array</td><td align="center">온체인 증명 기록</td></tr><tr><td align="center"><code>disputes</code></td><td align="center">array 또는 null</td><td align="center">이의 제기 기록, 없으면 null</td></tr></tbody></table>

#### 증명 항목:

|   **필드**  | **타입** |      **설명**     |
| :-------: | :----: | :-------------: |
|  `chain`  | string | `base` 또는 `bsc` |
| `tx_hash` | string |     트랜잭션 해시     |

#### 이의 제기 항목:

<table data-header-hidden><thead><tr><th width="222.2109375" align="center"></th><th width="203.828125" align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><strong>필드</strong></td><td align="center"><strong>타입</strong></td><td align="center"><strong>설명</strong></td></tr><tr><td align="center"><code>id</code></td><td align="center">int64</td><td align="center">이의 제기 식별자</td></tr><tr><td align="center"><code>status</code></td><td align="center">string</td><td align="center"><code>open</code>(진행 중) 또는 <code>closed</code>(종료)</td></tr><tr><td align="center"><code>submitter_selection</code></td><td align="center">string</td><td align="center">제출자가 올바르다고 주장하는 결과</td></tr><tr><td align="center"><code>reason_text</code></td><td align="center">string</td><td align="center">사유</td></tr><tr><td align="center"><code>submitted_at</code></td><td align="center">string</td><td align="center">RFC 3339 UTC 타임스탬프</td></tr><tr><td align="center"><code>decision</code></td><td align="center">object 또는 null</td><td align="center">종료된 경우에만 포함</td></tr></tbody></table>

#### 결정 객체:

<table data-header-hidden><thead><tr><th width="217.4296875" align="center"></th><th width="169.484375" align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><strong>필드</strong></td><td align="center"><strong>타입</strong></td><td align="center"><strong>설명</strong></td></tr><tr><td align="center"><code>type</code></td><td align="center">string</td><td align="center"><code>keep</code>(유지) 또는 <code>override</code>(번복)</td></tr><tr><td align="center"><code>partner_final_verdict</code></td><td align="center">string</td><td align="center">결정 이후의 최종 판정</td></tr><tr><td align="center"><code>reason_text</code></td><td align="center">string</td><td align="center">결정 사유</td></tr><tr><td align="center"><code>decided_at</code></td><td align="center">string</td><td align="center">RFC 3339 UTC 타임스탬프</td></tr></tbody></table>

참고:

* 이의 제기가 없으면 `disputes`는 `null`입니다(빈 배열이 아님).
* 일치하는 마켓이 없으면 `data.markets`는 빈 배열을 반환합니다.

***

### POST `/cournot/markets/dispute/submit`

최종 사용자를 대신해 이의를 제기합니다. API 키 인증이 필요합니다.

#### 헤더:

<table data-header-hidden><thead><tr><th width="266.7421875" align="center"></th><th width="304.3671875" align="center"></th></tr></thead><tbody><tr><td align="center"><strong>헤더</strong></td><td align="center"><strong>값</strong></td></tr><tr><td align="center"><code>Content-Type</code></td><td align="center"><code>application/json</code></td></tr><tr><td align="center"><code>x-api-key</code></td><td align="center">파트너 API 키</td></tr></tbody></table>

#### 요청 본문:

<table data-header-hidden data-search="false"><thead><tr><th width="205.22265625" align="center"></th><th align="center"></th><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><strong>필드</strong></td><td align="center"><strong>타입</strong></td><td align="center"><strong>필수</strong></td><td align="center"><strong>설명</strong></td></tr><tr><td align="center"><code>market_id</code></td><td align="center">int64</td><td align="center">예</td><td align="center">get_public_market에서 얻은 마켓 ID</td></tr><tr><td align="center"><code>submitter_id</code></td><td align="center">string</td><td align="center">예</td><td align="center">파트너 플랫폼에서 최종 사용자의 고유 식별자</td></tr><tr><td align="center"><code>submitter_name</code></td><td align="center">string</td><td align="center">예</td><td align="center">제출자의 표시 이름</td></tr><tr><td align="center"><code>submitter_selection</code></td><td align="center">string</td><td align="center">예</td><td align="center">제출자가 올바르다고 주장하는 결과</td></tr><tr><td align="center"><code>reason_text</code></td><td align="center">string</td><td align="center">예</td><td align="center">이의 제기 사유</td></tr><tr><td align="center"><code>submitted_at</code></td><td align="center">string</td><td align="center">예</td><td align="center">RFC 3339 UTC 타임스탬프</td></tr></tbody></table>

#### 요청 예시:

```json
curl -X POST "https://interface.cournot.ai/cournot/markets/dispute/submit" \
  -H "content-type: application/json" \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -d '{
    "market_id": 61,
    "submitter_id": "partner_user_1001",
    "submitter_name": "alice",
    "submitter_selection": "NO",
    "reason_text": "we believe the resolved outcome is incorrect based on source evidence",
    "submitted_at": "2026-04-28T10:30:00Z"
  }'
```

#### 응답 예시:

```json
{ "code": 0, "msg": "Success", "data": { "dispute_id": 4 } }
```

**비즈니스 규칙:**

* 파트너의 `source`(API 키에서 도출)는 해당 마켓의 source와 일치해야 합니다. 파트너 간 교차 이의 제기는 금지됩니다.
* `status = resolved`인 마켓에만 이의를 제기할 수 있습니다.
* 각 마켓에는 이의 제기를 최대 1건만 접수할 수 있습니다.

***

### 연동 워크플로

#### 표준 결과 확정 흐름:

1. 자사 마켓에 대해 `GET /cournot/markets/public`을 폴링합니다.
2. 마켓이 `status: resolved` 상태가 되면 `verdict`, `confidence`, `proofs`를 추출합니다.
3. 이 기록을 사용해 자사 플랫폼에서 해당 마켓을 정산합니다.

#### 이의 제기 처리 흐름:

1. 최종 사용자가 자사 플랫폼에서 판정에 이의를 제기합니다.
2. `POST /cournot/markets/dispute/submit`으로 이의 제기를 제출합니다.
3. 마켓 상태가 `resolved` → `disputed`로 전환됩니다.
4. Cournot이 내부 검토를 수행합니다.
5. 마켓은 `decision` 객체(`type: keep` 또는 `type: override`)와 함께 `closed` 상태가 됩니다.
6. `GET /cournot/markets/public`을 폴링해 최종 결정을 조회합니다.

#### 마켓 수명 주기:

<figure><img src="https://1059874529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNOU3GBemYhm2Po6mv3Hy%2Fuploads%2FojsEeK1bwTyQR0Yg7Qjn%2F10.%20Lifecycle.png?alt=media&amp;token=ec4b9f71-9434-4651-8cb2-64113a8c60ca" alt=""><figcaption></figcaption></figure>

***

기존 오라클은 신뢰할 수 있는 데이터를 온체인에서 사용할 수 있게 만들었습니다. Cournot은 신뢰할 수 있는 데이터를 의미 단위로 프로그래밍할 수 있게 만들고, 이를 인텔리전스로 확장하며, 궁극적으로 행동으로 이어지게 합니다.

<figure><img src="https://1059874529-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNOU3GBemYhm2Po6mv3Hy%2Fuploads%2FIt3h3pSTYS9ZwXtCEQWa%2F11.%20Cournot%20Protocol%20Building%20Oracle%204.0.png?alt=media&amp;token=aad2b9ea-f5df-4769-801c-61226ad9d47c" alt=""><figcaption></figcaption></figure>

예측시장은 아키텍처를 입증합니다. RWA 가격 산정은 시맨틱 집계를 입증합니다. 트레이딩 인텔리전스는 지속적 모니터링을 입증합니다. 에이전트 경제는 이 모든 것이 하나로 모이는 곳입니다.

**데이터 → 시맨틱 데이터 → 인텔리전스 → 행동.**

Cournot은 Oracle 4.0을 구축하고 있습니다.