# 모든 호출이 따르는 규칙은 무엇입니까?

여기서 시작 · 모든 호출에 chain, 세 가지 주소 표기, 소수점 여섯 자리 달러, 하나의 오류 형식

*API 가이드 · 7분 · 중급 · 개발자 · 규칙*

규칙은 여섯 가지이며, 모든 경로에 적용됩니다. `chain`을 명시적으로 넘기십시오 — 암묵적 기본값은 베이스(Base, 8453)이며, `chain_source: "default"`가 유일한 흔적입니다. 주소는 요청한 네트워크의 표기 방식으로 응답되며, 다른 종류의 체인 표기는 거부되지 않고 `address_respelled: true`로 표시됩니다. 모든 `*_usd6`는 미국 달러에 100만을 곱한 값입니다. 단독 `amount` 또는 `balance`는 토큰의 최소 단위이며 옆에 `decimals`가 있습니다. 오류는 하나의 형식을 공유합니다 — `error.code`로 분기하십시오. 네 개의 경로는 알 수 없는 매개변수를 거부하고, 나머지는 무시합니다. 모든 응답에는 요청 ID가 있습니다.

## 1. `chain`을 매번 넘기십시오

대부분의 조회는 하나의 네트워크에 관한 것이며, `chain`이 없으면 베이스에 대해 응답합니다. [OpenAPI](https://achivx.kr/academy/reference/api-methodology/) 명세는 이를 한 문장으로 말합니다: *without it most reads answer about Base, and an answer about the wrong network looks exactly like an answer.*(없으면 대부분의 조회는 베이스에 대해 응답하며, 잘못된 네트워크에 대한 응답도 겉보기에는 똑같이 응답처럼 보입니다.) 2026-10-24에 `chain` 없는 `GET /v1/addresses/0x28C6…1d60`은 완벽한 형식의 개요로 응답했습니다 — 베이스에 대한 것이었고, `chain_id: 8453`과 `"chain_source": "default"`가 유일한 단서였습니다. 같은 주소가 이더리움(Ethereum)에서는 동결 가능한 스테이블코인 네 개와 라벨을 갖지만, 베이스에서는 하나뿐입니다.

`chain`은 네 가지 표기를 받으며, 모두 동등합니다. ID(`1`), 문자열 ID(`"1"`), 슬러그(`ethereum`), CAIP-2 ID(`eip155:1`)입니다. 공백, 앞의 `+`, 앞의 0은 허용됩니다. `0x1`은 허용되지 않으며 — 허용되는 형식을 메시지에 담은 `400 invalid_chain`입니다. [배포](https://achivx.kr/academy/reference/glossary/#g-deployment)가 제공하지 않는 체인도 `400 invalid_chain`입니다: *unknown chain id — see GET /v1/networks for the chains this deployment serves*(알 수 없는 체인 ID — 이 배포가 제공하는 체인은 GET /v1/networks 참고)(`chain=999999`로 확인). ID 목록:

| 네트워크 | `chain` | 슬러그 |
|---|---|---|
| 이더리움(Ethereum) | `1` | `ethereum` |
| 옵티미즘(Optimism) | `10` | `optimism` |
| BNB 체인(BNB Chain) | `56` | `bnb-chain` |
| 베이스(Base) | `8453` | `base` |
| 아비트럼 원(Arbitrum One) | `42161` | `arbitrum` |
| 트론(Tron) | `728126428` | `tron` |
| 솔라나(Solana) | `-1` | `solana` |

두 경로는 의도적으로 이 규칙을 따르지 않습니다. `/v1/verify`는 `tx`만 받아 모든 네트워크를 검색합니다(여기에 `chain`을 넘기면 `400 unknown_param`). `chain` 없는 `/v1/freezes/acts`는 모든 네트워크를 나열하며, `"chain_id": null, "chain_source": "all_networks"`로 그렇다고 밝힙니다.

## 2. 주소: 세 가지 표기, 응답은 네트워크 자체의 표기로

`0x…`는 EVM 주소, `T…`는 트론, 32바이트 [base58](https://achivx.kr/academy/reference/glossary/#g-base58) 키는 솔라나입니다. 모든 주소 응답에는 두 필드가 있습니다. 보낸 그대로인 `requested_address`와, 같은 바이트를 `chain_id`의 표기 방식으로 나타낸 `address`(EVM 네트워크에서는 소문자 16진수)입니다. `/balances`만 `address`에 보낸 표기를 그대로 돌려줍니다.

다른 종류의 네트워크에 대해 요청하면 주소는 *거부되지 않고 다시 표기됩니다*. 2026-10-24에 트론 USDT 컨트랙트 `TR7NHq…j6t`를 `chain=1`로 요청하자 이더리움의 `0xa614f803b6fd780986a42c78ec9c7f77e6ded13c`에 대해 `"address_respelled": true`와 함께 응답했습니다 — 같은 바이트이며, 일반 키 계정인 경우에만 같은 소유자입니다. 표기 때문에 거부되는 유일한 경우는 `0x…` 또는 `T…` 주소를 솔라나에 대해 요청할 때입니다: `400 invalid_address` — *a Solana address is a 32-byte base58 public key, and this one is 20 bytes — ask with the chain it belongs to, or omit chain to let its spelling choose.*(솔라나 주소는 32바이트 base58 공개 키인데 이것은 20바이트입니다 — 해당 체인으로 요청하거나, chain을 생략해 표기가 선택하게 하십시오.) 주소가 전혀 아닌 문자열은 `invalid address` 메시지와 함께 `400 invalid_address`입니다.

## 3. 금액: `usd6`, `amount`, `decimals`

세 가지 관례가 모든 수치를 담습니다.

- **`_usd6`**로 끝나는 필드는 페그 1(USDC == USD) 기준 소수점 여섯 자리의 미국 달러입니다. 1,000,000으로 나누십시오. `"volume_usd6": 68012749860030611`은 680억 달러입니다.
- 단독 **`amount`**, **`balance`**, **`volume`**은 토큰 자체의 최소 단위이며, 옆에 항상 토큰의 `decimals`가 있습니다. [피드](https://achivx.kr/academy/courses/following-the-stablecoins/following-the-stablecoins-01-settlement-tables/) 행 `{"amount": "1047600000", "decimals": 6, "token": "USDC"}`는 1,047.60 USDC입니다. `decimals: 18`인 [USD1](https://achivx.kr/academy/issuers/bitgo/) 잔액 `"12634092351409304697742144"`는 1,260만 USD1입니다. 2^53을 넘을 수 있는 값은 **문자열**로 옵니다 — 부동소수점이 아니라 큰 정수로 파싱하십시오.
- 피드 행의 **`usd_amount`**는 표시용으로 같은 전송을 일반 십진수로 나타낸 것입니다. 계산에는 `amount`를 쓰십시오.

## 4. 하나의 오류 형식

모든 경로의 모든 거부는 다음과 같습니다.

```
{"error": {"code": "invalid_limit", "message": "limit must be 1..200", "request_id": "a4f869e6d8f3431d-ARN"}}
```

`code`는 [OpenAPI](https://achivx.kr/academy/reference/api-methodology/) `Error` 스키마가 열거하는 38개 값 중 하나입니다. `message`에는 해결 방법이 있으면 담깁니다. `request_id`는 문의 시 인용할 값입니다. HTTP 상태가 아니라 `code`로 분기하십시오 — `503`은 `timeout`, `busy`, `snapshot_pending`, `not_ready` 중 하나이며, 각각 요구하는 것이 다릅니다. 오류 응답은 `Cache-Control: no-store`입니다. 처리 방법은 [코드에서 오류와 한도 처리](https://achivx.kr/academy/api/errors-and-limits-in-code/)에 있습니다.

## 5. 알 수 없는 매개변수: 네 경로에서는 거부, 나머지에서는 무시

`/v1/transfers`, `/v1/verify`, `/v1/freezes/acts`, `/v1/freezes/proposals`는 모르는 매개변수에 대해 `400 unknown_param`으로 응답하며, 메시지에 아는 매개변수를 나열합니다 — 2026-10-24의 `/v1/transfers`: *accepted filters: payer, recipient, token, chain, tx, block, finality, dir, limit, cursor, offset (there is no touching-this-address filter: query payer and recipient separately)*(허용되는 필터: …(이 주소가 관련된 필터는 없음: payer와 recipient를 따로 조회)). 그 밖의 모든 곳에서는 철자가 틀린 매개변수가 조용히 무시되고 경로의 기본값이 적용되므로, 필터는 [레퍼런스](https://achivx.kr/academy/api/endpoint-reference/)에 적힌 그대로 정확히 쓰십시오.

## 6. 모든 응답은 추적할 수 있습니다

`X-Request-Id`는 모든 응답에 있습니다. 직접 보내면 그대로 돌아옵니다(2026-10-24에 `/v1/sanctions`에서 `X-Request-Id: academy-test-123`이 그대로 반환되었습니다). 엣지 캐시되는 조회 — `/v1/transfers`, `/v1/addresses/…`, `/v1/networks`, `/v1/tokens`, [`/v1/methodology`](https://stablescan.achivx.com/v1/methodology), `/v1/subscriptions` — 에서는 ID가 Cloudflare ray이며 보낸 ID는 반환되지 않습니다. `HIT`이면 스캐너가 요청을 아예 보지 못했으므로, 옆에 `cf-cache-status`를 함께 인용하십시오. 판정에는 `computed_at`이 있고, 주소 응답에는 `freshness_seconds`(해당 네트워크에서 가장 최근에 인덱싱된 전송의 경과 시간)와 `data_vintage`(네트워크의 [관측 기록이 시작되는 지점](https://achivx.kr/academy/concepts/coverage-and-freshness/) — 왼쪽 경계이지 최신성이 아님)가 있습니다.

## 표현에 관한 두 가지 규칙

실제 `/v1` 경로를 잘못된 메서드로 호출하면 `Allow` 헤더와 함께 `405 method_not_allowed`로 응답합니다(`DELETE /v1/networks` → `Allow: GET, HEAD`). 경로가 아닌 주소는 매뉴얼을 가리키는 메시지와 함께 JSON `404 not_found`로 응답합니다: *no route for GET /v1/nope. The /v1 surface is described in https://stablescan.achivx.com/agents.md.*(GET /v1/nope에 대한 경로가 없습니다. /v1 인터페이스는 https://stablescan.achivx.com/agents.md 에 설명되어 있습니다.) 둘 다 2026-10-24에 확인했습니다.

## Stablecoin scanner ACHIVX에서

- ID가 포함된 체인 표기: [/v1/networks](https://stablescan.achivx.com/v1/networks).
- 실시간으로 다시 표기된 주소: [이더리움에 대해 요청한 트론 USDT 컨트랙트](https://stablescan.achivx.com/v1/addresses/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t?chain=1) — `address_respelled`와 `requested_address`를 읽으십시오.
- 오류 열거값: [/openapi.json](https://stablescan.achivx.com/openapi.json)의 `Error` 스키마.

## 출처

- [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-24 조회)](https://stablescan.achivx.com/v1/networks)

## 더 알아보기

- [REST API는 어떻게 구성되어 있습니까?](https://achivx.kr/academy/for-agents/how-the-rest-api-is-organised/)
- [용어집](https://achivx.kr/academy/reference/glossary/)

## 관련 질문

- [API에 첫 요청을 보내려면 어떻게 합니까?](https://achivx.kr/academy/api/first-request/)
- [응답은 어떻게 읽습니까: unknown, null, 빈 목록, no-store](https://achivx.kr/academy/api/reading-an-answer/)
- [코드에서 오류, 요청 한도, 타임아웃을 처리하려면 어떻게 합니까?](https://achivx.kr/academy/api/errors-and-limits-in-code/)

여기서 시작 · 규칙 · 2026-10-24 작성, openapi.json, agents.md 및 당일 실제 호출 기반. 구조는 인용한 것이며, 수치는 날짜 기준이고 인덱스에 따라 바뀝니다.

---

출처: https://achivx.kr/academy/api/the-rules-every-call-follows/ · 영어 원문: https://achivx.com/academy/api/the-rules-every-call-follows.html