{"openapi":"3.1.0","info":{"title":"Bithomp (BYOK) API","version":"0.1.0","description":"Bithomp (BYOK) lets an AI assistant read your own Bithomp data through the Bithomp API with a key you supply (Bithomp API key (free plan: 10 requests per minute, non-commercial use)). Read-only: 10 tools (get_address, get_username, list_address_transactions, list_address_trustlines, list_tokens, search_tokens, get_token, list_token_holders, get_nft, list_nft_collections). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-bithomp.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-bithomp/docs"},"termsOfService":"https://connectorbay.com/byok-bithomp/terms"},"servers":[{"url":"https://byok-bithomp.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-bithomp/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_address":{"post":{"operationId":"get_address","summary":"Get an XRP Ledger account: balance, flags, owner count, domain and optionally the Bithomp username, service name, verifi","description":"Get an XRP Ledger account: balance, flags, owner count, domain and optionally the Bithomp username, service name, verified domain and first-seen details. Use for \"What is the balance and username of this XRP Ledger address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"XRP Ledger account address (r-address or X-address).","maxLength":80,"title":"Address","type":"string"},"username":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include the Bithomp username.","title":"Username"},"service":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include service details.","title":"Service"},"verified_domain":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include the verified domain when one exists.","title":"Verified Domain"},"inception":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include genesis, initial balance and first-seen time.","title":"Inception"},"ledger_info":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include the ledger account object (balance, flags, owner count, domain).","title":"Ledger Info"}},"required":["address"],"title":"get_addressArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_username":{"post":{"operationId":"get_username","summary":"Look up the XRP Ledger address behind a Bithomp username. Use for \"Which address belongs to the Bithomp username Bitstam","description":"Look up the XRP Ledger address behind a Bithomp username. Use for \"Which address belongs to the Bithomp username Bitstamp\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"description":"Bithomp or old rippletrade username.","maxLength":60,"title":"Username","type":"string"},"service":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include service details.","title":"Service"}},"required":["username"],"title":"get_usernameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_address_transactions":{"post":{"operationId":"list_address_transactions","summary":"List recent transactions of an XRP Ledger account, newest first, with type, hash, time and outcome. Use for \"What are th","description":"List recent transactions of an XRP Ledger account, newest first, with type, hash, time and outcome. Use for \"What are the latest transactions of this XRP Ledger address\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"XRP Ledger account address (r-address or X-address).","maxLength":80,"title":"Address","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of items to return (up to 100 on the free plan).","title":"Limit"},"type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Transaction type filter, such as Payment, OfferCreate or TrustSet.","title":"Type"},"filter_spam":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Filter out known spam transactions.","title":"Filter Spam"},"exclude_failures":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Exclude transactions that did not succeed.","title":"Exclude Failures"},"relevant_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Only transactions where the address is source, destination or had balance changes.","title":"Relevant Only"},"from_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date, ISO 8601 or unix seconds.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest date, ISO 8601 or unix seconds.","title":"To Date"},"marker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination marker returned by the previous page (paid plans only).","title":"Marker"}},"required":["address"],"title":"list_address_transactionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_address_trustlines":{"post":{"operationId":"list_address_trustlines","summary":"List the token balances (trustlines) held by an XRP Ledger account. Use for \"Which tokens does this XRP Ledger address h","description":"List the token balances (trustlines) held by an XRP Ledger account. Use for \"Which tokens does this XRP Ledger address hold\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"address":{"description":"XRP Ledger account address (r-address or X-address).","maxLength":80,"title":"Address","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of items to return (up to 100 on the free plan).","title":"Limit"}},"required":["address"],"title":"list_address_trustlinesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tokens":{"post":{"operationId":"list_tokens","summary":"List XRP Ledger issued tokens ranked by rating or holders, with issuer, supply, trustline and holder counts. Use for \"Wh","description":"List XRP Ledger issued tokens ranked by rating or holders, with issuer, supply, trustline and holder counts. Use for \"Which are the top XRP Ledger tokens by rating\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of items to return (up to 100 on the free plan).","title":"Limit"},"order":{"anyOf":[{"enum":["rating","trustlinesHigh","holdersHigh"],"type":"string"},{"type":"null"}],"default":"rating","description":"Sort order: rating, trustlinesHigh or holdersHigh.","title":"Order"},"issuer":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tokens from this issuer address.","title":"Issuer"},"currency":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tokens with this currency code.","title":"Currency"},"kyc":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Only tokens trusted by the community.","title":"Kyc"},"lptokens":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include AMM liquidity pool tokens.","title":"Lptokens"},"marker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination marker returned by the previous page (paid plans only).","title":"Marker"}},"title":"list_tokensArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_tokens":{"post":{"operationId":"search_tokens","summary":"Search XRP Ledger tokens by currency code or name fragment. Use for \"Find XRP Ledger tokens matching RLU\".","description":"Search XRP Ledger tokens by currency code or name fragment. Use for \"Find XRP Ledger tokens matching RLU\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"item":{"description":"Currency code, name or issuer fragment to search for.","maxLength":60,"title":"Item","type":"string"}},"required":["item"],"title":"search_tokensArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_token":{"post":{"operationId":"get_token","summary":"Get one XRP Ledger token by issuer and currency: supply, holders, trustlines, issuer details and optional issuer TOML. U","description":"Get one XRP Ledger token by issuer and currency: supply, holders, trustlines, issuer details and optional issuer TOML. Use for \"What is the supply and holder count of this XRP Ledger token\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"issuer":{"description":"Issuer account address of the token.","maxLength":80,"title":"Issuer","type":"string"},"currency":{"description":"Currency code of the token (3 letters or 40 hex characters).","maxLength":40,"title":"Currency","type":"string"},"toml":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include TOML data published on the issuer domain.","title":"Toml"}},"required":["issuer","currency"],"title":"get_tokenArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_token_holders":{"post":{"operationId":"list_token_holders","summary":"List the largest holders of an XRP Ledger token (rich list) with balances. Use for \"Who are the biggest holders of this ","description":"List the largest holders of an XRP Ledger token (rich list) with balances. Use for \"Who are the biggest holders of this XRP Ledger token\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"issuer":{"description":"Issuer account address of the token.","maxLength":80,"title":"Issuer","type":"string"},"currency":{"description":"Currency code of the token (3 letters or 40 hex characters).","maxLength":40,"title":"Currency","type":"string"},"summary":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include a token summary with supply, holders and trustlines.","title":"Summary"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum number of items to return (up to 100 on the free plan).","title":"Limit"},"marker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination marker returned by the previous page (paid plans only).","title":"Marker"}},"required":["issuer","currency"],"title":"list_token_holdersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_nft":{"post":{"operationId":"get_nft","summary":"Get one XLS-20 NFT by id: issuer, owner, flags, collection and optionally URI, metadata and history. Use for \"Who owns t","description":"Get one XLS-20 NFT by id: issuer, owner, flags, collection and optionally URI, metadata and history. Use for \"Who owns this XRP Ledger NFT\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"nft_id":{"description":"NFT id, 64 hex characters.","maxLength":64,"title":"Nft Id","type":"string"},"uri":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include URI and URL.","title":"Uri"},"metadata":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"Include metadata.","title":"Metadata"},"history":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include ownership and sale history.","title":"History"},"sell_offers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include sell offers.","title":"Sell Offers"},"buy_offers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"Include buy offers.","title":"Buy Offers"}},"required":["nft_id"],"title":"get_nftArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_nft_collections":{"post":{"operationId":"list_nft_collections","summary":"List XLS-20 NFT collections, optionally filtered by name or issuer. Use for \"Which NFT collections on the XRP Ledger mat","description":"List XLS-20 NFT collections, optionally filtered by name or issuer. Use for \"Which NFT collections on the XRP Ledger match zerpmon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search by collection name and description.","title":"Search"},"issuer":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Collection issuer address.","title":"Issuer"},"order":{"anyOf":[{"enum":["createdNew","createdOld","updatedNew","updatedOld"],"type":"string"},{"type":"null"}],"default":"createdNew","description":"createdNew, createdOld, updatedNew or updatedOld.","title":"Order"},"marker":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination marker returned by the previous page (paid plans only).","title":"Marker"}},"title":"list_nft_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}