Add a New YAML Exchange

Add a new exchange $ARGUMENTS by creating a YAML configuration file.

IMPORTANT RULES:

• NEVER modify Go code. The YAML handler supports a fixed set of features. If an exchange cannot be implemented using the available YAML fields, tell the user clearly: "This exchange cannot be implemented via YAML configuration because [reason]." and stop.
• Do NOT read Go source code during implementation. Only read existing YAML files in <PROJECT_ROOT>/config/prod/exchanges/ for reference patterns.
• Do NOT search for API documentation yourself. The user MUST provide either the API documentation text or a link to it. If the user has not provided documentation, ask them: "Please provide the exchange's API documentation or a link to it so I can inspect the endpoints."
• Keep all output simple and beginner-friendly. Do NOT show raw API responses, internal field mappings, or technical details of the YAML structure to the user. Just show the final result.

Tool Permissions

Before starting, tell the user:

To avoid approving every tool call manually, run this skill with --allowedTools or press a (allow all) when prompted. This skill uses Read, Write, Edit, Bash, WebFetch, and Glob — all safe, local operations.

Step 0: Locate the coinpaprika-services Project

All file operations and tests run against the github.com/coinpaprika/coinpaprika_services repository. Locate it using only non-Bash tools to avoid permission prompts:

1. First, check if the project path is already available in the additional working directories provided in the environment. If you see a path containing coinpaprika-services/config/prod/exchanges, derive the project root from it (strip the suffix).
2. If not found there, use the Glob tool to search for the checker binary: Glob(pattern="**/cmd_local/config_ticker_checker/main.go", path=os.path.expanduser("~")) and derive the project root from the result.
3. Only if both above fail, ask the user: "Where is the coinpaprika_services repository cloned on your machine?"

Do NOT use Bash (test -f, find, git rev-parse) to locate the project — these require shell permission approval.

Store the result as PROJECT_ROOT and use it for all file paths below (e.g., <PROJECT_ROOT>/config/prod/exchanges/).

Finding reference YAML files: When you need to search existing YAML files for patterns (e.g., finding a Pattern 3 example), use the Grep tool instead of bash grep. Example: Grep(pattern="@symbol", path="<PROJECT_ROOT>/config/prod/exchanges/").

Step 1: Get API Documentation from the User

Do NOT use WebSearch to find documentation. The user must provide one of:

• A link to the API documentation (use WebFetch to read it)
• The API documentation text directly
• Specific endpoint URLs to inspect (use WebFetch to check the JSON responses)

If the user has not provided any of the above, ask them before proceeding.

Once you have the documentation or endpoint URLs, use WebFetch to inspect the actual JSON response structure of each endpoint. Understand:

• Where the data array/object is in the response (for data_path)
• What fields contain: symbol/pair name, base currency, quote currency, last price, volume
• Whether the ticker endpoint contains full market info or if a separate markets endpoint is needed
• Whether tickers are returned in a single endpoint or per-market (one endpoint per pair)

You need to identify endpoints for:

1. Tickers/Market data - an endpoint that returns price and volume data
2. Markets/Trading pairs (sometimes needed) - an endpoint that lists available trading pairs with base/quote currency info
3. Order books (optional) - an endpoint that returns order book data (asks/bids)

IMPORTANT: When the user provides a documentation link, always browse the surrounding API documentation (parent pages, sibling endpoints, navigation menus) to check if an order book endpoint exists. Use WebFetch on the documentation index/parent page to discover all available endpoints. Order books are valuable and should be configured whenever available.

Step 2: Determine the YAML Pattern

Based on the API structure, determine which pattern to use. There are 3 patterns for tickers:

Pattern 1: All-in-one (tickers contain everything)

Use when the ticker endpoint returns symbol, base, quote, price, and volume in one response.

internal_id: exchange_name
tickers:
  url: https://api.example.com/tickers
  data_path: "@this"          # or "data", "result", etc.
  field_paths:
    symbol: "pair_name"        # field with market symbol like "BTC/USDT"
    base_currency_symbol: "base"
    quote_currency_symbol: "quote"
    last_price: "last"
    base_volume: "volume"

Pattern 2: Separate markets + tickers endpoints

Use when the ticker endpoint lacks base/quote currency info and a separate markets endpoint provides it.

internal_id: exchange_name
markets:
  url: https://api.example.com/markets
  data_path: "data"
  field_paths:
    id: "symbol"              # field to join markets with tickers
    symbol: "symbol"
    base_currency_symbol: "baseCoin"
    quote_currency_symbol: "quoteCoin"
tickers:
  url: https://api.example.com/tickers
  data_path: "data"
  field_paths:
    id: "symbol"              # must match markets.id
    last_price: "close"
    base_volume: "baseVol"

Pattern 3: Per-market ticker endpoints

Use when each trading pair has its own ticker endpoint. Requires a markets endpoint. Use %s as placeholder for the market symbol.

internal_id: exchange_name
markets:
  url: https://api.example.com/symbols
  data_path: "data"
  field_paths:
    id: "pair"
    symbol: "pair"
    base_currency_symbol: "base"
    quote_currency_symbol: "quote"
tickers:
  url: https://api.example.com/ticker?pair=%s
  data_path: "data"
  field_paths:
    id: "pair"                # or "@symbol" if response has no symbol field
    last_price: "last"
    base_volume: "volume"

Step 3: Available YAML Fields Reference

This is the complete list of all supported YAML fields.

Top-level

• internal_id (required): Unique identifier. Lowercase, no spaces (use _). Usually the exchange name.

markets section (optional - only needed for patterns 2 and 3)

• url (required): Markets endpoint URL
• data_path (required): JSON path to data. Use "@this" if data is at root level.
• field_paths (required):
  • id (required): Field to join with tickers. Use "@key" if the key of the JSON object is the id.
  • symbol (required): Market symbol field. Use "@key" if the key of the JSON object is the symbol.
  • symbol_separator (optional): Character separating base/quote in the symbol (e.g., "_", "-", "/"). Use this when symbol contains both base and quote joined by a separator.
  • symbol_inverted (optional): true if the symbol is QUOTE_BASE instead of BASE_QUOTE. Only relevant when symbol_separator is set.
  • base_currency_symbol (optional): Field with base currency symbol. Not needed if symbol_separator is used.
  • quote_currency_symbol (optional): Field with quote currency symbol. Not needed if symbol_separator is used.

tickers section (required)

• url (required): Tickers endpoint URL. Use %s as placeholder for per-market endpoints (pattern 3). The %s is replaced with symbol from the markets section.
• data_path (required): JSON path to data. Use "@this" if data is at root level.
• field_paths (required):
  • id (optional): Field to join with markets. Use "@key" for JSON object key. Use "@symbol" when the per-market endpoint response has no symbol field (the symbol from the URL placeholder is used instead). Required when markets section exists.
  • symbol (optional): Market symbol field. Use "@key" for JSON object key. Used when no markets section exists.
  • symbol_separator (optional): Character separating base/quote in the symbol (e.g., "_", "-", "/"). Use this when symbol contains both base and quote joined by a separator.
  • symbol_inverted (optional): true if the symbol is QUOTE_BASE instead of BASE_QUOTE. Only relevant when symbol_separator is set.
  • base_currency_symbol (optional): Field with base currency symbol. Not needed if symbol_separator is used or if markets section provides this info.
  • quote_currency_symbol (optional): Field with quote currency symbol. Not needed if symbol_separator is used or if markets section provides this info.
  • last_price (required): Field with last trade price.
  • last_price_reversed (optional): true if the price in the data is quote/base instead of base/quote (the handler will invert it: 1.0 / price).
  • base_volume (required*): Field with base volume. *Either base_volume or quote_volume must be provided.
  • quote_volume (required*): Field with quote volume. Use instead of base_volume when only quote volume is available. It will be auto-converted to base volume using the formula: base_volume = quote_volume / last_price. *Either base_volume or quote_volume must be provided.
  • include_zero_volume (optional): true to include tickers with zero volume (normally they are filtered out).

order_books section (optional)

• url (required): Order book endpoint URL. Use %s as placeholder for market symbol. The %s is replaced with symbol from markets section (if exists) or from tickers section.
• data_path (optional): JSON path to data. Rarely needed — typically the nesting is handled via the asks/bids paths directly.
• field_paths (required):
  • asks (required): JSON path to asks array (e.g., "asks", "data.asks"). Can include nested path to handle data nesting.
  • bids (required): JSON path to bids array (e.g., "bids", "data.bids"). Can include nested path to handle data nesting.
  • order_price (required): Field/index for price within each order. Use "0" for array index (when orders are arrays like ["price", "amount"]), or a field name like "price" when orders are objects.
  • order_amount (required): Field/index for amount within each order. Use "1" for array index, or a field name like "quantity" when orders are objects.

Nested field access

Fields can be nested using dots: "ticker.last", "data.result.price". This works for all string field values including data_path and all field_paths entries.

Special values

• "@this" — Use as data_path when data is at the root level of the JSON response.
• "@key" — Use as id, symbol, or other field when the value is the key of the JSON object (not a field inside it).
• "@symbol" — Use as id in tickers.field_paths when using per-market endpoints (pattern 3) and the response has no field identifying the market. The symbol from the URL placeholder is used.
• %s — URL placeholder replaced with the market symbol. Used in tickers.url (pattern 3) and order_books.url.

Step 4: Create the YAML File

Write the YAML file to: <PROJECT_ROOT>/config/prod/exchanges/<exchange_name>.yaml

The <exchange_name> should be:

• Lowercase
• No spaces (use _ instead)
• No numbers at the start
• Similar to the exchange name

Step 5: Test with config_ticker_checker

Run the checker from the project root:

cd <PROJECT_ROOT> && go run cmd_local/config_ticker_checker/main.go config/prod/exchanges/<exchange_name>.yaml

Expected successful output

The checker should print 3 sample ticks and optionally 3 sample order books. Each tick should have:

• MarketSymbol - non-empty
• BaseCurrencySymbol - non-empty
• QuoteCurrencySymbol - non-empty
• LastPrice - non-zero
• Volume - non-zero (unless include_zero_volume is set)

If order books are configured, each sample order book entry must also have:

• Price - non-zero
• Quantity/Amount - non-zero

If any of these values are zero, the endpoint is not valid or the field mapping is wrong — treat it as a test failure and fix before proceeding.

If the test fails

1. Read the error message carefully
2. Re-check the API response structure by fetching the endpoint again with WebFetch
3. Adjust the YAML file (fix data_path, field_paths, etc.)
4. Re-run the checker
5. If after 3 attempts it still fails, inform the user with the specific error

Step 6: Report Test Results

Keep the output simple and short. Do NOT show raw API responses, field mappings, or YAML internals.

If test passed:

Show the user a simple summary table of 3 sample ticks so they can verify the data looks correct (price is price, volume is volume, etc.):

Test passed! Here are 3 sample ticks — please verify the data looks correct:

Market	Base	Quote	Last Price	Volume
BTC_USDT	BTC	USDT	65432.10	1234.56
...	...	...	...	...

If order books were also tested, show 1 sample order book:

Sample order book for BTC_USDT:

	Price	Amount
Ask 1	65433.00	0.5
Ask 2	65434.00	1.2
Bid 1	65431.00	0.8
Bid 2	65430.00	2.1

Then ask: "Does this look correct? If yes, do you want me to commit and push this exchange?"

Wait for the user to confirm the data looks right before proceeding.

If test failed:

Show:

❌ Exchange <exchange_name> could not be added.

• Error: <short error summary>

Remove the YAML file if the exchange does not work after all attempts. Stop here.

Step 7: Commit and Push (only if user agrees)

If the user says yes, commit and push the new YAML file in the coinpaprika-services repository:

cd <PROJECT_ROOT> && git add config/prod/exchanges/<exchange_name>.yaml && git commit -m "[yaml-exchange-skill] Add <exchange_name> exchange" && git push

The commit message MUST start with [yaml-exchange-skill] to clearly indicate it was created by this skill.

After successful commit and push, show:

Next steps:

1. Map <internal_id> to the exchange in the Coinpaprika admin panel
2. Run deploy-fix insert_raw_ticks on the #rollout Slack channel
3. (Only if order books were configured) Run deploy-fix update_order_books on the #rollout Slack channel

If the user declines to commit and push:

Show:

⚠️ The YAML file is saved locally but NOT committed. Remember to commit and push it before proceeding with the deployment steps.

Troubleshooting Common Issues

Error	Likely Cause	Fix
market symbol is empty	Wrong symbol or @key path	Check the API response for the correct symbol field
base currency symbol is empty	Missing base_currency_symbol or wrong symbol_separator	Add base/quote fields or fix separator
last price is zero	Wrong last_price path	Check the actual field name in the API response
volume is zero	Wrong volume path or exchange has no volume	Try quote_volume instead, or set include_zero_volume: true
could not read the yaml file	File path issue	Ensure the file exists and has .yaml extension
HTTP errors	API may be geo-restricted or rate-limited	Try again, check if API requires auth (if so, cannot use YAML)
market id is empty	Wrong id path in markets	Check which field uniquely identifies a market
invalid tick: market symbol is empty	id in tickers doesn't match id in markets	Ensure both id fields reference the same value

What CANNOT Be Done via YAML

If an exchange requires any of the following, tell the user it cannot be implemented via YAML:

• Authentication (API keys, signatures, tokens)
• WebSocket connections
• Pagination to get all markets/tickers
• POST requests (only GET is supported)
• Custom headers
• Rate limiting configuration
• Response formats other than JSON (XML, CSV, etc.)
• Complex data transformations beyond simple field mapping
• Multiple ticker endpoints that need to be merged