AGENTS.md: Migrating from GoPlus to Tok{In}

This file gives AI coding agents (Claude Code, Cursor, Copilot, etc.) the context they need to migrate an existing GoPlus token-security integration over to Dedaub's Tok{In} API with minimal code changes.

Source of truth: https://docs.dedaub.com/docs/token_safety/tokin/

If you are an AI agent helping a developer migrate, read this file end-to-end before editing their code. The sections are ordered so that the first three give you everything needed for a one-line drop-in swap; the rest covers field-level differences, edge cases, and known gaps.

1. TL;DR: the one-line swap

GoPlus's token_security endpoint can be replaced by Tok{In} with three changes:

Base URL → https://tokin-api.dedaub.com
Path → /token/{chain}/{token_address} (chain is a name, not a numeric chain id; see §6)
Auth → X-API-Key: <YOUR-API-KEY> header (instead of GoPlus's ?api_key= query param or app-id/secret signing)

Append ?response_format=goplus to receive field values in GoPlus's schema with "1"/"0" string-boolean encoding. The outer envelope is different (see §2.1): fields live under features, not at the top level, so a literal drop-in is rarely possible without one small parser change.

# Before (GoPlus)
curl 'https://api.gopluslabs.io/api/v1/token_security/1?contract_addresses=0xABC...'

# After (Tok{In}, GoPlus-compatible response)
curl -H 'X-API-Key: YOUR-API-KEY' \
  'https://tokin-api.dedaub.com/token/ethereum/0xABC...?response_format=goplus'

2. Endpoint reference

GET https://tokin-api.dedaub.com/token/{chain}/{token_address}
GET https://tokin-api.dedaub.com/token/{chain}/{token_address}?response_format=goplus

Headers:
  X-API-Key: <required>

Query param	Values	Default	Effect
`response_format`	`dedaub` \| `goplus`	`dedaub`	`goplus` reshapes the body to GoPlus's schema and string-boolean encoding.

The native dedaub schema is richer (typed booleans, additional fields, structured tax info). Use it for greenfield code; use goplus only when you are migrating existing GoPlus parsers and want to defer schema changes.

2.1 Response envelope (read this before parsing)

Tok{In} always wraps the result in this envelope, regardless of response_format:

{
  "chain": "ethereum",
  "contract_address": "0xA0b8...eB48",
  "features": { /* SafetyFeatures (dedaub) | GoPlusMappedFeatures (goplus) */ },
  "error": ""
}

This differs from GoPlus's { "code": 1, "message": "OK", "result": { "0xABC...": { ... } } } shape in two ways that matter to a migrating client:

Fields are nested under features, not under result["<address>"]. Update every accessor: body.is_open_source → body.features.is_open_source.
Errors come via HTTP status code + error string, not an in-body code/message pair. On non-2xx, features is null and error carries the human-readable reason.

Full response schema: see tokin.md.

Every /token route needs an X-API-Key header. A person gets one by signing in at https://tokin.dedaub.com/login and creating it in the dashboard.

If you are an agent running without a person present, you cannot do that: sign-in needs a mailbox. Request a capped trial key instead.

curl -X POST 'https://tokin-api.dedaub.com/agent-keys' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "LLM agent screening tokens before a user buys, ~200 scans/day",
       "contact": "[email protected]"}'

{
  "api_key": "...",
  "plan": "agent",
  "api_calls_per_month": 200,
  "api_calls_per_day": 50,
  "rate_limit_per_minute": 10,
  "next_step": "Send this key as the X-API-Key header on every request, ..."
}

reason is required and contact is optional. The reason is recorded so a person at Dedaub can see who uses this and for what. It is not verified and it grants nothing — the allowance is what limits you, not what you write.

Registration is idempotent. Asking again from the same network returns the key you already have, along with the allowance you have already partly spent. This is deliberate, and it is the thing most likely to surprise you: requesting another key is not a way to get more calls.

Four things to do with this, in the order they will bite:

Store the key, but do not panic if you lose it. Re-registering returns the same key rather than failing, so a client that has lost its key can recover. It will not get a fresh allowance.
Treat the trial as a trial. The allowance is small on purpose — enough to build and demonstrate an integration against a handful of tokens, and not enough to run a product on. Ask the developer you are working for to sign in and create a full key before shipping.
Do not retry a 402. See §7.1. A spent allowance does not refill, and asking for another key will not produce one.
Do not embed a trial key in code you hand to a user. It is bound to your allowance, not theirs, and the first thing that happens at scale is that it runs out for everyone at once.

3. Migration steps for an AI agent

When asked to migrate a codebase from GoPlus to Tok{In}, follow this sequence:

Locate the GoPlus call sites. Grep for gopluslabs.io, token_security, goplus, and known SDK imports (e.g. goplus-sdk-py, @goplus/sdk-node).
Identify the auth mechanism in use. GoPlus integrations vary: anonymous, ?api_key=, or app-id/secret signed access tokens. All three collapse to a single X-API-Key header in Tok{In}.
Translate the chain identifier. GoPlus uses numeric chain IDs in the path (/token_security/1); Tok{In} uses names (/token/ethereum/...). See §6 for the full mapping. If the codebase passes chain IDs around as integers, add a small lookup helper rather than rewriting every call site.
Update the URL builder and add the X-API-Key header. Append ?response_format=goplus if the existing parser relies on GoPlus field names and "1"/"0" strings; otherwise migrate to the native dedaub schema in the same change.
Audit field reads. Cross-reference every field the code reads against §4. Pay attention to:
- Computed fields (transfer_pausable, is_anti_whale, etc.): these are derived, not 1:1.
- Always-null fields (§4): if downstream code branches on them, simplify the branch or wire them to a different signal.
Update error handling. Tok{In} returns standard HTTP codes (§7); GoPlus historically returned 200 with a code field in the body. Replace body-code checks with HTTP status checks.
Update rate-limit handling. Tok{In} emits standard Retry-After plus X-RateLimit-* and X-Quota-* headers (§8). Wire any retry/backoff logic to those headers.
Run the test suite. If there isn't one for token-security calls, add at least one integration test against a known token (e.g. USDC on Ethereum: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) before declaring the migration done.

Do not silently delete GoPlus fields the user's code reads; flag them as TODOs (especially the always-null set in §4) so the developer can decide what to do.

4. Field mapping (Tok{In} `dedaub` → GoPlus)

When response_format=goplus, the server applies these mappings. All booleans become the strings "1" (true) or "0" (false).

Direct mappings

Tok{In} (Dedaub)	GoPlus	Notes
`is_open_source`	`is_open_source`	bool → `"1"`/`"0"`
`is_proxy`	`is_proxy`	bool → `"1"`/`"0"`
`mint_or_burn_function`	`is_mintable`	bool → `"1"`/`"0"`
`owner_address`	`owner_address`	string
`can_selfdestruct`	`selfdestruct`	bool → `"1"`/`"0"`
`external_call`	`external_call`	bool → `"1"`/`"0"`
`is_in_dex`	`is_in_dex`	bool → `"1"`/`"0"`
`receive_tax`	`buy_tax`	decimal as string
`send_tax`	`sell_tax`	decimal as string
`cannot_buy`	`cannot_buy`	bool → `"1"`/`"0"`
`tax_can_be_modified`	`slippage_modifiable`	bool → `"1"`/`"0"`
`trading_cooldown`	`trading_cooldown`	bool → `"1"`/`"0"`
`creator_address`	`creator_address`	string
`creator_percent`	`creator_percent`	decimal as string
`is_launchpad_token`	`launchpad_token`	bool → `"1"`/`"0"`

⚠ Tax direction is inverted. send_tax → sell_tax and receive_tax → buy_tax. Make sure any code computing slippage matches the renamed semantic.

⚠ buy_tax / sell_tax are pool-aware. The mapper first walks features.dex[] and uses the first pool with non-null buy_tax / sell_tax, falling back to the contract-level receive_tax / send_tax only if no pool reports a value. The result is usually closer to real swap behavior than GoPlus's contract-level tax, but it can disagree with the contract-level fields in the same response.

Additional fields populated in `goplus` mode

Beyond the GoPlus-spec fields, the response also carries:

token_name, token_symbol, total_supply: populated when known.
holders[]: array of { address, balance, percent }. Note that holder_count itself is null (see below) but the holders[] array is populated.

Computed mappings (derived, not 1:1)

GoPlus field	Derived from	Logic
`transfer_pausable`	`cannot_buy`, `pause_status_can_be_modified`	`True` if either is `True`
`is_blacklisted`	`has_blacklist_or_whitelist`	same value (temporary)
`is_whitelisted`	`has_blacklist_or_whitelist`	same value (temporary)
`is_anti_whale`	`has_trading_cap`, `has_position_cap`	`True` if either is `True`
`anti_whale_modifiable`	`trading_cap_can_be_modified`, `position_cap_can_be_modified`	`True` if either is `True`
`hidden_owner`	`allowance_bypass`, `privileged_spenders`	`True` when the bypass is address specific, so at least one address is named
`owner_change_balance`	`owner_can_change_balance`	same value

⚠ Blacklist/whitelist ambiguity. Both flags map from the same source, so the API cannot distinguish blacklist-only, whitelist-only, or both. Code that branches on one vs. the other should be reviewed.

⚠ hidden_owner is tri-state underneath. It maps from the allowance-bypass check, and is "1" only in the address-specific case: a universal bypass (allowance_bypass true, privileged_spenders empty) means the token authorises nobody in particular, which is a broken ERC20 rather than a hidden owner, so it maps to "0". It is null when the check could not run, which is not the same as "0". Treat null as unknown, never as safe. In dedaub mode read allowance_bypass and privileged_spenders directly; the latter carries the actual addresses that can drain a holder.

Currently always `null`

These GoPlus fields exist in the response shape but are not yet tracked by Tok{In}. If downstream code reads them, treat the read as a TODO and either remove the dependency or substitute a different signal:

cannot_sell_all
can_take_back_ownership
gas_abuse
personal_slippage_modifiable
lp_total_supply
is_airdrop_scam
trust_list
holder_count
owner_balance
owner_percent
is_honeypot (not listed in upstream public docs but always returns null today)

⚠ is_honeypot is the field GoPlus consumers most often gate trades on. Migration should not treat its absence as "not a honeypot". Derive an equivalent signal from cannot_buy, the per-pool dex[].buy_success/sell_success (in dedaub mode), and tax fields, or block on the field being unavailable.

⚠⚠ buy_success / sell_success are not booleans. They are four-valued: true, false, "pending" (simulation still running) and null (no simulation was attempted for that pool; common for bonding-curve pools). null and "pending" mean unknown and carry no signal. A honeypot check written as if (!pool.sell_success) will flag every healthy token whose pool was not simulated. Test === false explicitly. See tokin.md.

For the full GoPlus mapping (direct, computed, and always-null fields), see tokin.md.

5. Code examples

Python (`requests`)

import os, requests

API_KEY = os.environ["TOKIN_API_KEY"]
BASE = "https://tokin-api.dedaub.com"

def token_security(chain: str, address: str, *, goplus_compat: bool = True) -> dict:
    params = {"response_format": "goplus"} if goplus_compat else None
    r = requests.get(
        f"{BASE}/token/{chain}/{address}",
        params=params,
        headers={"X-API-Key": API_KEY},
        timeout=30,
    )
    if r.status_code == 429:
        retry_after = int(r.headers.get("Retry-After", "60"))
        raise RuntimeError(f"rate limited; retry after {retry_after}s")
    r.raise_for_status()
    return r.json()

TypeScript (`fetch`)

const TOKIN_BASE = "https://tokin-api.dedaub.com";

export async function tokenSecurity(
  chain: "ethereum" | "binance" | "base" | "arbitrum" | "avalanche" | "robinhood",
  address: string,
  { goplusCompat = true } = {},
) {
  const url = new URL(`${TOKIN_BASE}/token/${chain}/${address}`);
  if (goplusCompat) url.searchParams.set("response_format", "goplus");

  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.TOKIN_API_KEY! },
  });

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("Retry-After") ?? 60);
    throw new Error(`rate limited; retry after ${retryAfter}s`);
  }
  if (!res.ok) throw new Error(`tokin ${res.status}: ${await res.text()}`);
  return res.json();
}

Go (`net/http`)

Idiomatic client with context.Context, wrapped errors, and a typed ErrRateLimited so callers can branch on errors.As and respect Retry-After:

package tokin

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
	"strconv"
	"time"
)

// ErrRateLimited is returned when Tok{In} responds with HTTP 429.
// Callers should sleep for RetryAfter before retrying.
type ErrRateLimited struct{ RetryAfter time.Duration }

func (e *ErrRateLimited) Error() string {
	return fmt.Sprintf("tokin rate limited; retry after %s", e.RetryAfter)
}

// Client is a minimal Tok{In} HTTP client. Zero value is not usable; call NewClient.
type Client struct {
	APIKey  string
	BaseURL string
	HTTP    *http.Client
}

// NewClient builds a Client with sensible defaults. APIKey is read from TOKIN_API_KEY.
func NewClient() *Client {
	return &Client{
		APIKey:  os.Getenv("TOKIN_API_KEY"),
		BaseURL: "https://tokin-api.dedaub.com",
		HTTP:    &http.Client{Timeout: 30 * time.Second},
	}
}

// TokenSecurity fetches token-safety analysis for the given chain and address.
// When goplusCompat is true, the response is reshaped to GoPlus's schema with
// "1"/"0" string booleans.
func (c *Client) TokenSecurity(ctx context.Context, chain, address string, goplusCompat bool) (map[string]any, error) {
	u, err := url.Parse(fmt.Sprintf("%s/token/%s/%s", c.BaseURL, chain, address))
	if err != nil {
		return nil, fmt.Errorf("build url: %w", err)
	}
	if goplusCompat {
		q := u.Query()
		q.Set("response_format", "goplus")
		u.RawQuery = q.Encode()
	}

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, u.String(), nil)
	if err != nil {
		return nil, fmt.Errorf("new request: %w", err)
	}
	req.Header.Set("X-API-Key", c.APIKey)

	resp, err := c.HTTP.Do(req)
	if err != nil {
		return nil, fmt.Errorf("do request: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusTooManyRequests {
		secs, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
		if secs <= 0 {
			secs = 60
		}
		return nil, &ErrRateLimited{RetryAfter: time.Duration(secs) * time.Second}
	}
	if resp.StatusCode >= 400 {
		return nil, fmt.Errorf("tokin %d", resp.StatusCode)
	}

	var out map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		return nil, fmt.Errorf("decode body: %w", err)
	}
	return out, nil
}

For typed access, replace map[string]any with a generated struct that mirrors the response shape documented in tokin.md.

Rust (`reqwest` + `tokio`)

# Cargo.toml
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde_json = "1"
thiserror = "1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use std::env;
use std::time::Duration;

use reqwest::{Client, StatusCode};
use serde_json::Value;
use thiserror::Error;

const BASE: &str = "https://tokin-api.dedaub.com";

#[derive(Debug, Error)]
pub enum TokinError {
    #[error("rate limited; retry after {0:?}")]
    RateLimited(Duration),
    #[error("tokin {status}: {body}")]
    Http { status: u16, body: String },
    #[error(transparent)]
    Request(#[from] reqwest::Error),
    #[error("missing TOKIN_API_KEY")]
    MissingKey,
}

/// Fetch token-safety analysis. When `goplus_compat` is true, the response uses
/// GoPlus's schema with `"1"`/`"0"` string booleans.
pub async fn token_security(
    chain: &str,
    address: &str,
    goplus_compat: bool,
) -> Result<Value, TokinError> {
    let api_key = env::var("TOKIN_API_KEY").map_err(|_| TokinError::MissingKey)?;
    let url = format!("{BASE}/token/{chain}/{address}");

    let mut req = Client::new()
        .get(&url)
        .header("X-API-Key", api_key)
        .timeout(Duration::from_secs(30));
    if goplus_compat {
        req = req.query(&[("response_format", "goplus")]);
    }

    let resp = req.send().await?;

    if resp.status() == StatusCode::TOO_MANY_REQUESTS {
        let secs = resp
            .headers()
            .get("Retry-After")
            .and_then(|v| v.to_str().ok())
            .and_then(|s| s.parse::<u64>().ok())
            .unwrap_or(60);
        return Err(TokinError::RateLimited(Duration::from_secs(secs)));
    }

    let status = resp.status();
    if !status.is_success() {
        let body = resp.text().await.unwrap_or_default();
        return Err(TokinError::Http { status: status.as_u16(), body });
    }

    Ok(resp.json().await?)
}

For typed access, replace serde_json::Value with a #[derive(Deserialize)] struct mirroring the GoPlus schema (or the native Dedaub shape documented in tokin.md).

Chain-id translation helper

If existing GoPlus code carries numeric chain ids:

const CHAIN_ID_TO_NAME: Record<number, string> = {
"ethereum",
"binance",
"base",
"arbitrum",
"avalanche",
"robinhood",
};

6. Supported chains

Name (use in path)	Chain ID
`ethereum`	1
`binance`	56
`base`	8453
`arbitrum`	42161
`avalanche`	43114
`robinhood` (New)	4663

Any other chain GoPlus supports (Polygon, Optimism, Solana, etc.) is not currently available on Tok{In}. Surface this as a blocker rather than silently dropping the call.

⚠ Robinhood Chain (4663) has no GoPlus equivalent. It is a Tok{In}-only chain, so a migration will have no existing call site to translate, but if the codebase enumerates supported chains as a closed list (union type, enum, allowlist), add robinhood to it rather than leaving 4663 to fall through to the unsupported-chain path.

7. HTTP response codes

Code	Meaning
200	Success
401	Missing or invalid API key
402	A trial allowance is spent (§2.2). Not retryable — see below
422	Validation error: malformed EVM address or burn/null address (e.g. `0x000…000`, `0xdead…dead`)
429	Rate limit or quota exceeded
500	Internal server error (or upstream analysis failure)

On 422 and 500 the envelope is still {chain, contract_address, features: null, error: "<reason>"}; the error string is the source of the human-readable reason.

GoPlus's habit of returning 200 with an in-body code field does not apply here. Branch on HTTP status instead.

7.1 `error_code`, and why 402 is not 429

A refusal about you rather than about a token carries a machine-readable error_code at the top level of the body:

{
  "error_code": "api_key_required",
  "error": "API Key is missing. Send it as the X-API-Key header.",
  "detail": "API Key is missing. Send it as the X-API-Key header.",
  "next_step": "Humans: sign in and create a key. Automated callers: POST /agent-keys with a `reason` for a free trial key."
}

`error_code`	Status	What to do
`api_key_required`	401	Get a key (§2.2). Do not retry without one.
`free_quota_exhausted`	402	Stop. The allowance does not refill. Sign in for a full account.

Branch on error_code, never on the prose, which gets reworded.

The 402 is deliberately not a 429, and the distinction matters most to you. A 429 means "wait and try again", and a correct client sleeps and retries. A spent trial allowance never becomes available again, so the same retry loop runs forever and never succeeds. If your client has one retry policy for all 4xx, give 402 its own branch that stops.

8. Rate limits & quotas

There are three independent enforcement tiers, each emitting its own header set on 429:

Tier	Headers on 429	`Retry-After`?
Per-minute QPS	`Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`	yes
Daily quota	`Retry-After`, `X-Quota-Daily-Limit`, `X-Quota-Daily-Used`	yes
Monthly quota	`X-Quota-Monthly-Limit`, `X-Quota-Monthly-Used`	no

Two practical implications:

Retry strategy must branch on which header set is present. Per-minute and daily 429s have a Retry-After you can sleep on; a monthly-quota 429 means "wait until next billing period" and there is no header telling you when. Treat that case as fatal for the current period.
Headers are emitted only on the failing 429, not on successful responses. Clients cannot proactively monitor remaining budget, only learn about it on rejection. Pace requests defensively rather than racing the budget.

Trial keys (§2.2) are a fourth case and behave differently. All three tiers above still apply, but an exhausted monthly allowance on a trial key answers 402 with error_code: free_quota_exhausted rather than 429. That is the one refusal in this API that is permanent for the period, and it is given its own status precisely so a retry loop can tell it apart from a wait.

9. Common migration pitfalls

Reading fields at the wrong nesting level. GoPlus puts fields under result["<address>"]; Tok{In} puts them under features (see §2.1). This is the most common silently-wrong outcome of an unreviewed AI migration.
Trusting is_honeypot as a kill switch. It always returns null today (§4). GoPlus integrations that gate trades on is_honeypot === "1" will treat every token as safe after migration. Replace with a derived signal (cannot_buy, per-pool dex[].buy_success/sell_success, tax checks) or hard-block when the field is unavailable.
Treating a per-pool null as a failed trade. dex[].buy_success / sell_success return null when a pool was never simulated and "pending" while one is running; neither is a "no". Falsy checks turn both into "cannot sell", which is the inverse of the truth for a perfectly tradeable token (§4).
Treating "1"/"0" as truthy/falsy in JS. The string "0" is truthy. Use explicit === "1" checks or convert at the boundary.
Reading always-null fields without a guard (see §4). If a GoPlus integration relies on holder_count or owner_percent, they must be sourced elsewhere or the feature degraded.
Reading hidden_owner === "0" as "no hidden owner". It is null whenever the allowance-bypass check could not run, and "0" for a universal bypass, which is worse rather than better (§4). Anything gating on drain risk should read allowance_bypass and privileged_spenders in dedaub mode.
Forgetting the tax inversion. send_tax/receive_tax (Tok{In} native) are not the same direction as sell_tax/buy_tax until the GoPlus mapper renames them. Note also that buy_tax/sell_tax may come from per-pool DEX data (§4) and disagree with the contract-level tax.
Hard-coding chain IDs in the URL. Tok{In} uses chain names; failing to translate produces 422s, not 404s.
Expecting a second registration to yield a second allowance. Registration is idempotent per network (§2.2): you get the same key and the same partly-spent budget back. A client that reacts to a 402 by registering again will loop without ever gaining a call.
Retrying a 402 as though it were a 429. The allowance does not refill (§7.1). A shared 4xx retry policy turns this into an infinite loop that never succeeds and looks, from the outside, exactly like abuse.
Confusing response_format=goplus with the data being GoPlus's data. The schema is GoPlus-shaped, but the underlying analysis is Dedaub's (Gigahorse-based bytecode analysis). Detection coverage and false-positive characteristics will differ.

10. When to drop GoPlus compatibility mode

response_format=goplus is a migration aid, not the long-term recommendation. Once the rest of the integration is stable, prefer the native dedaub schema for:

typed booleans (no "1"/"0" parsing),
richer tax structure,
access to fields not representable in the GoPlus shape (e.g. structured cap modification flags),
forward compatibility as new detectors land.

The native response shape and field reference are documented in tokin.md.

1. TL;DR: the one-line swap​

2. Endpoint reference​

2.1 Response envelope (read this before parsing)​

2.2 Getting a key when you cannot sign in​

3. Migration steps for an AI agent​

4. Field mapping (Tok{In} dedaub → GoPlus)​

Direct mappings​

Additional fields populated in goplus mode​

Computed mappings (derived, not 1:1)​

Currently always null​

5. Code examples​

Python (requests)​

TypeScript (fetch)​

Go (net/http)​

Rust (reqwest + tokio)​

Chain-id translation helper​

6. Supported chains​

7. HTTP response codes​

7.1 error_code, and why 402 is not 429​

8. Rate limits & quotas​

9. Common migration pitfalls​

10. When to drop GoPlus compatibility mode​