Contacts

Withdrawal contacts (read + reference edit)

GET /v2/contacts

List contacts

Saved withdrawal destinations. A contact is what POST /v2/withdrawals sends to, and its asset is fixed — a withdrawal whose asset does not match its destination contact is rejected. Contacts cannot be created through v2; add them from the Skipo dashboard.

Parámetros

Parámetro	En	Tipo	Requerido	Descripción
page	query	integer	no	Default: 1.
limit	query	integer	no	Default: 25.
type	query	INTERNAL | EXTERNAL_CRYPTO | BANK_ACCOUNT	no	Filter by contact type.

Respuestas

Código	Descripción	Cuerpo
200	Éxito.	data: ContactResource[] · pagination: PaginationMeta
401	application/problem+json (RFC 9457) — branch on code, not on the status: unauthorized (not retryable), key_expired (not retryable), key_revoked (not retryable).	—
403	application/problem+json (RFC 9457) — branch on code, not on the status: insufficient_scope (not retryable), ip_not_allowed (not retryable), api_access_disabled (not retryable).	—
429	application/problem+json (RFC 9457) — branch on code, not on the status: rate_limited (retryable).	—
500	application/problem+json (RFC 9457) — branch on code, not on the status: internal_error (retryable).	—
502	application/problem+json (RFC 9457) — branch on code, not on the status: downstream_unavailable (retryable).	—
503	application/problem+json (RFC 9457) — branch on code, not on the status: maintenance (retryable).	—

---

GET /v2/contacts/{contactId}

Get a contact by id

Use it to confirm a destination before signing a withdrawal — the asset and the address or account it resolves to are what the withdrawal will actually use.

Parámetros

Parámetro	En	Tipo	Requerido	Descripción
contactId	path	string	sí

Respuestas

Código	Descripción	Cuerpo
200	Éxito.	ContactResource
401	application/problem+json (RFC 9457) — branch on code, not on the status: unauthorized (not retryable), key_expired (not retryable), key_revoked (not retryable).	—
403	application/problem+json (RFC 9457) — branch on code, not on the status: insufficient_scope (not retryable), ip_not_allowed (not retryable), api_access_disabled (not retryable).	—
404	application/problem+json (RFC 9457) — branch on code, not on the status: not_found (not retryable).	—
429	application/problem+json (RFC 9457) — branch on code, not on the status: rate_limited (retryable).	—
500	application/problem+json (RFC 9457) — branch on code, not on the status: internal_error (retryable).	—
502	application/problem+json (RFC 9457) — branch on code, not on the status: downstream_unavailable (retryable).	—
503	application/problem+json (RFC 9457) — branch on code, not on the status: maintenance (retryable).	—

---

PATCH /v2/contacts/{contactId}

Edit a contact's reference/alias

Edits YOUR label for the contact, nothing else. The destination itself — address, network, bank account, asset — is immutable through this API, so this call can never redirect where money goes. To change a destination, create a new contact from the dashboard.

Parámetros

Parámetro	En	Tipo	Requerido	Descripción
contactId	path	string	sí

Cuerpo de la petición — UpdateContactReferenceDto

Respuestas

Código	Descripción	Cuerpo
200	Éxito.	ContactResource
400	application/problem+json (RFC 9457) — branch on code, not on the status: validation_error (not retryable).	—
401	application/problem+json (RFC 9457) — branch on code, not on the status: unauthorized (not retryable), key_expired (not retryable), key_revoked (not retryable).	—
403	application/problem+json (RFC 9457) — branch on code, not on the status: insufficient_scope (not retryable), ip_not_allowed (not retryable), api_access_disabled (not retryable).	—
404	application/problem+json (RFC 9457) — branch on code, not on the status: not_found (not retryable).	—
422	application/problem+json (RFC 9457) — branch on code, not on the status: unprocessable (not retryable).	—
429	application/problem+json (RFC 9457) — branch on code, not on the status: rate_limited (retryable).	—
500	application/problem+json (RFC 9457) — branch on code, not on the status: internal_error (retryable).	—
502	application/problem+json (RFC 9457) — branch on code, not on the status: downstream_unavailable (retryable).	—
503	application/problem+json (RFC 9457) — branch on code, not on the status: maintenance (retryable).	—

---

Esquemas

BankContactDetails

Campo	Tipo	Descripción
assetSymbol	string | null	Asset this account settles in. Always a FIAT code — a bank account cannot be denominated in a crypto asset or a tokenised equity. Ej.: CLP.
nationalId	string | null	The account holder's national id.
bankId	string | null
bankName	string | null	Ej.: Banco de Chile.
accountTypeId	string | null
bankAccountType	string | null	Ej.: CHECKING.
bankAccountNumber	string | null
accountEmail	string | null

ContactResource

Campo	Tipo	Descripción
id	string
reference	string | null
type	INTERNAL | EXTERNAL_CRYPTO | BANK_ACCOUNT	Which kind of destination this is, and therefore which detail block is present: EXTERNAL_CRYPTO → crypto, BANK_ACCOUNT → bank, INTERNAL → neither.
alias	string
createdAt	string
updatedAt	string
crypto (opcional)	any	Present only when type is EXTERNAL_CRYPTO.
bank (opcional)	any	Present only when type is BANK_ACCOUNT.

CryptoContactDetails

Campo	Tipo	Descripción
assetSymbol	string | null	Asset code this address receives. Ej.: BTC.
assetName	string | null	Ej.: Bitcoin.
networkSymbol	string | null	Network the address lives on, exactly as it was stored when the contact was created — passed through UNNORMALIZED. Kept for compatibility; it is NOT a stable key. Use networkId below instead — it is the canonical chain identifier and it is published on GET /v2/assets too, so the two sides now join directly. Why this field cannot be that key: it conflates the chain with the token standard and with the chain native coin. A BNB Smart Chain contact reports BNB here (the native COIN), while a movement on the same chain, to the same address, reports BEP20 (the TOKEN STANDARD). Neither is the chain, which is BSC. The inconsistency is not confined to contacts. Measured on production, the MOVEMENT rows carry two spellings for one chain: 164,192 withdrawals say BEP20 while 1,614 say BSC; 1,501 say ETH while 455 say ERC20; Avalanche appears as both AVAXC and AVAX. The field also carries values that are not networks at all (INTERNAL on 56,745 withdrawals, FIAT_NETWORK on 15,396, plus EARN and REDPAY) and prose (Dogecoin, Stellar Network, XRP Ledger). Movements are unchanged and still read this way. GET /v2/assets no longer publishes a networkSymbol at all — it was removed rather than rewritten, because the reference surface now reads the canonical registry (crypto_network) and any value carried over would have silently changed meaning. Contacts keep theirs because here it is the contact own stored data, not a lookup. Ej.: BTC.
networkName	string | null	Human-readable network name, for DISPLAY. It agrees with GET /v2/assets and with the movement payloads, but do not key on it: it is prose, and Ethereum (ERC20) is the one name on production that does not resolve to a single network. To match a contact against an asset supported networks, use networkId. It is the canonical chain identifier and it is now published on BOTH this resource and GET /v2/assets, so the two sides join directly. Earlier revisions of this field said to match on the name until a canonical registry existed — it exists, and this is it. Ej.: Bitcoin.
networkId	string | null	The CANONICAL chain identifier, from maintainers chain registry — BSC, ETH, TRON, BITCOIN, STELLAR_NETWORK. This is the field to match against the networkId published by GET /v2/assets, and it is a stable key, which networkSymbol above is not. It is also what the industry keys on: Binance identifies BNB Smart Chain as network: "BSC", and this says BSC too. null only when the network does not resolve in the registry. Ej.: BITCOIN.
evmChainId	number | null	EIP-155 chain id for an EVM chain — 56 for BNB Smart Chain, 1 for Ethereum. null on a non-EVM chain. Ej.: 1.
networkNativeAsset	string | null	The chain NATIVE COIN symbol — BNB for BNB Smart Chain. This is the asset that pays gas, NOT an identifier for the chain; networkId is that. Note networkSymbol above happens to carry this value today, which is exactly the confusion networkId resolves. Ej.: BTC.
address	string | null	The on-chain destination address.
tag	string | null	Destination tag / memo, for chains that require one (XRP, XLM…). Null otherwise.

PaginationMeta

Campo	Tipo	Descripción
page	number	Ej.: 1.
limit	number	Ej.: 25.
totalItems	number	Ej.: 100.
totalPages	number	Ej.: 4.

Problem

Campo	Tipo	Descripción
type	string	Stable problem-type URI. Resolves to docs for this error. Ej.: https://docs.skipo.com/errors/rate_limited.
title	string	Short, human-readable summary (stable, English). Ej.: Rate limit exceeded.
status	number	HTTP status code. Ej.: 429.
code	string	Stable machine-readable error code (equals the last path segment of type). Ej.: rate_limited.
retryable	boolean	Whether retrying the identical request may succeed. Ej.: true.
detail (opcional)	string	Human-readable, possibly localized detail.
instance (opcional)	string	The request path that produced the error.
traceId (opcional)	string	Trace id — joins BigQuery api_request and Cloud Logging.

UpdateContactReferenceDto

Campo	Tipo	Descripción
reference	string	New reference/alias label for the contact (does not change the destination).

---

Volver a la referencia de endpoints. Ver también: Paginación · Errores · Ids y correlación.