# REST API는 어떻게 구성되어 있습니까?

REST API · 여덟 개 그룹의 35개 경로, 하나의 오류 봉투, 체인은 명시적으로 전달

*에이전트용 · 6분 · 고급 · 개발자 · REST*

/openapi.json(OpenAPI 3.1, API 1.4.0)은 하나의 서버 아래 여덟 개 태그로 35개 경로를 설명합니다: addresses(9), freezes(6), registry(7), stats(5), feed(3), attestation(1), watchlists(경로 2개, 작업 3개), liveness(2). watchlists를 제외한 모든 것은 공개되어 있고 읽기 전용이며 인증이 필요 없습니다. 오류는 하나의 봉투를 공유합니다 — HTTP 상태가 아니라 `error.code`로 분기하십시오 — 그리고 `chain`을 받는 모든 호출에는 `chain`을 전달해야 합니다(`/v1/verify`는 `tx`만 받습니다).

## 명세

`GET /openapi.json`은 *REST 인터페이스의 OpenAPI 3.1 명세입니다 — 모든 `/v1` 경로와 그 매개변수 및 오류 코드, 코드에 타입이 있는 곳에서는 타입이 지정된 응답 스키마. 이것은 무엇이 전송되는지를 말하고, 이 매뉴얼은 그것이 무슨 뜻인지를 말합니다*(매뉴얼, §1). 그 자체의 `info.description`은 두 규칙을 짧게 담고 있습니다: *모든 호출에 `chain`을 명시적으로 전달하십시오: 없으면 대부분의 조회가 베이스(Base) 기준으로 답하며, 잘못된 네트워크에 대한 응답은 정확히 정상 응답처럼 보입니다*, 그리고 *오류는 하나의 봉투(`Error`)를 공유합니다. HTTP 상태가 아니라 `error.code`로 분기하십시오. 마감 시간을 넘긴 조회는 `code: timeout`과 `Retry-After`가 붙은 `503`입니다.*

## 여덟 개 그룹 (2026-10-13 조회)

| 태그 | 경로 | 답하는 내용 |
|---|---|---|
| **addresses** (9) | `/v1/addresses/{address}`와 `/risk`, `/exposure`, `/approvals`, `/walk`, `/graph`, `/balances`, `/volume`, `/heuristics` | 컴플라이언스 응답을 담은 개요, 스킬에 대응하는 네 개, REST에만 있는 네 개 |
| **freezes** (6) | `/v1/freezes?tx=`, `/v1/freezes/acts`, `/proposals`, `/networks`, `/guide`, `/v1/tokens/{token}/freezes` | 한 거래가 발생시킨 기록, 기록 원장, [멀티시그 제안](https://achivx.kr/academy/guides/issuer-freezes/), 네트워크별 색인, 스테이블코인별 권한, 심볼별 요약 |
| **registry** (7) | `/v1/networks`, `/v1/tokens`, `/v1/tokens/{address}/contract`, `/v1/sanctions`, `/v1/search`, [`/v1/methodology`](https://stablescan.achivx.com/v1/methodology), `/v1/subscriptions` | 네트워크 목록(`settled` 포함), 체인별 스테이블코인 [레지스트리](https://achivx.kr/academy/reference/glossary/#g-registry), [검증된 컨트랙트](https://achivx.kr/academy/courses/following-the-stablecoins/following-the-stablecoins-03-token-pages/) 기록, [OFAC](https://achivx.kr/academy/reference/glossary/#g-ofac-sdn) 데이터셋 상태, 검색창 뒤의 검색, 방법론, [구독](https://achivx.kr/academy/guides/watchlists-and-alerts/)이 있는 곳 |
| **stats** (5) | `/v1/stats/home`, `/overview`, `/slo`, `/v1/tokens/{token}/routes`, `/addresses` | 하나의 문서로 된 [대시보드](https://achivx.kr/academy/guides/dashboard/), 실시간 개요, 서비스의 예산, 토큰별 순위 |
| **feed** (3) | `/v1/transfers`, `/v1/verify`, `/v1/sync/status` | [정산 피드](https://achivx.kr/academy/guides/settlement-tables/), 모든 네트워크에서 해시 하나 조회(`tx`만 — 그곳에서 `chain`은 `400 unknown_param`), 인덱서 최신성 |
| **attestation** (1) | `POST /v1/verify-attestation` | 본문을 그 증명과 대조해 검사 |
| **watchlists** (경로 2개, 작업 3개) | `GET`/`POST /v1/watchlists`, `DELETE /v1/watchlists/{id}` | 베어러 등급: [알림](https://achivx.kr/academy/guides/watchlists-and-alerts/) 규칙 |
| **liveness** (2) | `/health`, `/ready` | 프로세스가 떠 있고 데이터베이스가 응답함 — *인덱싱에 대해서는 아무것도 말하지 않습니다* |

## 전체에 걸친 규약

모든 `*_usd6` 필드는 소수 6자리 미국 달러입니다 — 1,000,000으로 나누십시오. 접미사 없는 `volume` 필드는 원시 토큰 최소 단위입니다: 10^`decimals`로 나누십시오. `chain`은 이를 받는 모든 경로에서 하나의 규칙으로 읽힙니다: id(`1`, `10`, `56`, `8453`, `42161`, `728126428`, `-1`), 문자열로 쓴 같은 id, 슬러그, 또는 CAIP-2 id. 빈 값이나 공백 값은 매개변수를 생략한 것으로 보아 경로의 기본값이 적용됩니다 — 대부분의 조회에서 베이스(기록 원장 `/v1/freezes/acts`만은 `400`으로 거부). `0x1`은 허용 형식을 나열하는 메시지와 함께 `400 invalid_chain`으로 거부됩니다(2026-10-13 확인). 모든 주소 응답은 체인이 어떻게 선택되었는지 밝히고(`chain_source`: `explicit`, `default`, `address_form`) `chains_with_data`, `freshness_seconds`, `requested_address`, `address_respelled`를 담습니다. 알 수 없는 `/v1` 경로는 `request_id`와 매뉴얼 안내가 붙은 JSON `404 not_found`로, 잘못된 메서드는 `Allow`가 붙은 `405`로 답합니다. API가 답할 수 있는 모든 상태와 코드, 그리고 각각의 메시지와 요구하는 조치는 [응답은 어떤 것일 수 있습니까?](https://achivx.kr/academy/for-agents/every-answer-code-on-every-door/)에 있습니다.

## Stablecoin scanner ACHIVX에서

[openapi.json 열기 ↗](https://stablescan.achivx.com/openapi.json)

- 명세: [/openapi.json](https://stablescan.achivx.com/openapi.json). 그 의미: [/agents.md](https://stablescan.achivx.com/agents.md) §2.
- id를 가져올 레지스트리: [/v1/networks](https://stablescan.achivx.com/v1/networks), [/v1/tokens?chain=1](https://stablescan.achivx.com/v1/tokens?chain=1).

## 출처

- [REST 인터페이스의 OpenAPI 3.1 명세 (API 1.4.0)](https://stablescan.achivx.com/openapi.json)
- [에이전트 매뉴얼 — agents.md (버전 2026-10-05)](https://stablescan.achivx.com/agents.md)
- [GET /v1/networks (2026-10-13 조회)](https://stablescan.achivx.com/v1/networks)

## 더 알아보기

- [기계로 사이트 읽기](https://achivx.kr/academy/reference/api-methodology/)
- [레슨: 하나의 질문, 세 가지 접근 경로](https://achivx.kr/academy/courses/the-scanner-for-agents/the-scanner-for-agents-02-one-question-three-doors/)

## 관련 질문

- [페이지 나누기와 캐시는 어떻게 합니까: 커서, ETag, If-None-Match?](https://achivx.kr/academy/for-agents/how-to-page-and-cache/)
- [한도는 무엇이며, 거부는 어떤 모습입니까?](https://achivx.kr/academy/for-agents/what-are-the-limits-and-refusals/)
- [숫자는 어떻게 만들어지며, 누가 서명합니까?](https://achivx.kr/academy/for-agents/how-the-numbers-are-produced-and-signed/)

REST API · REST · 2026-10-13 작성, 스캐너 자체의 기계용 문서와 그날 조회한 실시간 응답을 바탕으로 했습니다. 구조는 그대로 인용했으며, 수치는 날짜 기준이고 인덱스에 따라 바뀝니다.

---

출처: https://achivx.kr/academy/for-agents/how-the-rest-api-is-organised/ · 영어 원문: https://achivx.com/academy/for-agents/how-the-rest-api-is-organised.html