# 사이트 검색창처럼 이름이나 심볼로 검색하려면 어떻게 합니까?

레지스트리, 검색, 시장 데이터 · 심볼로 스테이블코인을, 커뮤니티 라벨 이름으로 지갑을 — 입력이 주소, 해시, 블록이 아닐 때 검색창이 요청하는 것

*API 가이드 · 5분 · 입문 · 개발자 · GET /v1/search*

`GET /v1/search?q=`는 사이트 검색창이 주소, 거래 해시, 블록 번호가 아닌 모든 입력에 대해 호출하는 것입니다. `tokens[]`는 `q`와 정확히 또는 접두어로 일치하는 레지스트리 심볼이며, 각각 열어야 할 페이지와 네트워크가 함께 나옵니다. `addresses[]`는 커뮤니티 라벨 이름에 `q`가 포함된 지갑으로, 가장 잘 일치하는 것부터 — 정확히 일치, 접두어 일치, 짧은 이름 순 — 나옵니다. `q`는 2~64자입니다. 라벨은 귀속이지 검증된 신원이 아니며, 응답의 `note`가 그렇게 밝힙니다.

## 요청

```
curl -s 'https://stablescan.achivx.com/v1/search?q=USDT'
```

```
{
  "query": "USDT",
  "tokens": [
    {"symbol": "USDT", "url": "/usdt-explorer",
     "networks": [{"chain_id": -1, "network": "solana", "url": "/solana/stablecoin/usdt"}, {"chain_id": 1, "network": "ethereum", "url": "/ethereum/stablecoin/usdt"}, "… +4 more"]},
    {"symbol": "USDT0", "url": "/optimism/stablecoin/usdt0",
     "networks": [{"chain_id": 10, "network": "optimism", "url": "/optimism/stablecoin/usdt0"}, {"chain_id": 42161, "network": "arbitrum", "url": "/arbitrum/stablecoin/usdt0"}]}
  ],
  "addresses": [
    {"chain_id": 8453, "network": "base", "address": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2", "name": "USDT", "category": "contract", "url": "/base/address/0xfde4…9bb2"},
    {"chain_id": 1, "network": "ethereum", "address": "0xaef027f94008430bf4fc27ffabb49ea6f1dd3414", "name": "USDT0", "category": "bridge", "url": "/ethereum/address/0xaef0…3414"},
    "… +18 more"
  ],
  "note": "tokens: stablecoins whose symbol matches (exact or prefix) on the networks this scanner indexes. addresses: wallets whose community label name contains the query, best match first …"
}
```

2026-10-24에 `q=binance`는 토큰 없이, 이더리움(Ethereum)에서 `category: "exchange_hot"`인 *Binance*라는 이름의 주소 20개로 응답했습니다 — 사이트가 검색창 아래에 *ten wallets, +10 more*(지갑 10개, +10개 더)로 보여 주는 목록입니다. 한 글자 쿼리는 `400 invalid_query`입니다: *q must be 2..64 characters*(q는 2~64자여야 합니다).

[첫 번째 요청](https://achivx.kr/academy/api/first-request/)의 헬퍼 세 개로 한 같은 호출:

**Python**

```
hits = scan("/v1/search", q="binance")
for a in hits["addresses"][:10]:
    print(a["network"], a["address"], a["name"], a["category"])
for t in hits["tokens"]:
    print(t["symbol"], "on", [n["network"] for n in t["networks"]])
```

**Go**

```
var hits struct {
	Tokens []struct {
		Symbol   string `json:"symbol"`
		URL      string `json:"url"`
		Networks []struct {
			ChainID int    `json:"chain_id"`
			Network string `json:"network"`
		} `json:"networks"`
	} `json:"tokens"`
	Addresses []struct {
		ChainID  int    `json:"chain_id"`
		Network  string `json:"network"`
		Address  string `json:"address"`
		Name     string `json:"name"`
		Category string `json:"category"`
	} `json:"addresses"`
}
if err := get("/v1/search", url.Values{"q": {"binance"}}, &hits); err != nil {
	return err
}
```

**TypeScript**

```
type Search = {
  query: string;
  tokens: { symbol: string; url: string; networks: { chain_id: number; network: string; url: string }[] }[];
  addresses: { chain_id: number; network: string; address: string; name: string; category: string; url: string }[];
};
const hits = await scan<Search>("/v1/search", { q: "binance" });
```

## 필드별 설명

**`tokens[]`** — `symbol`, 해당 페이지의 `url`(크로스체인 허브 [`/usdt-explorer`](https://stablescan.achivx.com/usdt-explorer)가 있으면 그것, 없으면 첫 번째 네트워크의 [토큰 페이지](https://achivx.kr/academy/guides/token-pages/)), 각 네트워크의 `url`이 담긴 `networks[]`. 심볼에 대한 정확 일치 또는 접두어 일치입니다. `USDT`는 `USDT`와 `USDT0`을 찾습니다.

**`addresses[]`** — `chain_id`, `network`, `address`, 라벨의 `name`과 `category`(`exchange_hot`, `contract`, `bridge`, `issuer`, `custodial`, …), 페이지 `url`. 라벨 이름의 부분 문자열 일치이며, 순서는 정확 일치, 접두어 일치, 짧은 이름 순입니다. 한 번의 호출에 최대 20개 — 검색창은 10개를 보여 주고 *+10 more*라고 표시합니다. 라벨은 [출처 기록](https://achivx.kr/academy/concepts/labels-and-attribution/)이 있는 커뮤니티 귀속이지 신원이 아니며, 체인마다 고르지 않습니다. 같은 거래소가 한 네트워크에서는 이름이 붙어 있고 다른 네트워크에서는 익명일 수 있습니다.

**`note`** — 매번 붙는 규칙입니다. `max-age=60`.

## 검색이 맞지 않는 경우

주소, 해시, 블록 번호는 검색 대상이 아닙니다. [개요](https://achivx.kr/academy/api/address-overview/), [`/v1/verify`](https://achivx.kr/academy/api/find-a-transaction/) 또는 [`block=`을 붙인 피드](https://achivx.kr/academy/api/settlement-feed/)를 여십시오. 또한 *이름*은 출발점이지 답이 아닙니다. 라벨은 커뮤니티가 어떤 주소들을 *Binance*라고 부르는지 알려 주고, 개요와 위험 판정이 각 주소에 대해 알려 줍니다.

## Stablecoin scanner ACHIVX에서

- JSON으로 본 검색: [/v1/search?q=USDT](https://stablescan.achivx.com/v1/search?q=USDT), [/v1/search?q=binance](https://stablescan.achivx.com/v1/search?q=binance).
- [첫 페이지](https://stablescan.achivx.com/) 검색창에 입력한 같은 쿼리 — 그 아래의 목록과 개수를 제한하는 줄.

## 출처

- [REST 인터페이스의 OpenAPI 3.1 명세(API 1.4.0)](https://stablescan.achivx.com/openapi.json)
- [GET /v1/search?q=USDT(2026-10-24 조회)](https://stablescan.achivx.com/v1/search?q=USDT)

## 더 알아보기

- [검색하기](https://achivx.kr/academy/getting-started/searching/)
- [라벨과 귀속](https://achivx.kr/academy/concepts/labels-and-attribution/)

## 관련 질문

- [API는 어떤 네트워크와 스테이블코인을 알고 있으며, 이 컨트랙트는 검증되었습니까?](https://achivx.kr/academy/api/networks-and-tokens/)
- [주소가 제재 대상인지, 동결되었는지, 알려진 서비스인지 확인하려면 어떻게 합니까?](https://achivx.kr/academy/api/address-overview/)
- [거래소 전체를 읽으려면 어떻게 합니까: 주소, 흐름, 잔액](https://achivx.kr/academy/api/exchanges/)

레지스트리, 검색, 시장 데이터 · GET /v1/search · 2026-10-24 작성, openapi.json, agents.md 및 당일 실제 호출 기반. 구조는 인용한 것이며, 수치는 날짜 기준이고 인덱스에 따라 바뀝니다.

---

출처: https://achivx.kr/academy/api/search/ · 영어 원문: https://achivx.com/academy/api/search.html