# @oasisomniverse/web4-api - [@oasisomniverse/web4-api](#oasisomniverseweb4-api) - [About WEB 4](#about-web-4) - [Previous Versions](#previous-versions) - [About The OASIS Omniverse](#about-the-oasis-omniverse) - [Benefits Of Building On The WEB 4 OASIS API](#benefits-of-building-on-the-web-4-oasis-api) - [WEB 4 OASIS API Packages](#web-4-oasis-api-packages) - [Javascript](#javascript) - [Unity](#unity) - [C#](#c) - [Do You Want To Get Involved?](#do-you-want-to-get-involved) - [Install](#install) - [Quick start](#quick-start) - [Calling any endpoint](#calling-any-endpoint) - [Auth & sessions](#auth--sessions) - [Module examples](#module-examples) - [Module reference](#module-reference) - [Regenerating](#regenerating) - [Testing](#testing) - [Full documentation](#full-documentation) - [Troubleshooting](#troubleshooting) Isomorphic (Node 18+ and browser) JavaScript/TypeScript-friendly client for the **WEB 4 OASIS API** - full coverage of the OASIS ONODE WebAPI: Avatar, Karma, Data, Wallet, NFT, Holochain, HyperDrive, Keys, Map, Provider and every other controller (32 modules, 483 operations). Zero dependencies. Wraps the global `fetch`. Works the same in Node and the browser. ## About WEB 4 > **"One avatar, one karma, every world."** WEB 4 is the universal unification layer of the OASIS Omniverse — one avatar, one SSO login and one karma reputation score that works across 40+ blockchains, databases and Web2/Web3 providers, so every world, app and game you build shares the same identity, reputation and wallet. No more silos, no more walled gardens, no single point of failure. WEB 4 is the foundation everything else in the ecosystem is built on top of — see the full **[OASIS Omniverse](https://oasisomniverse.one)** (WEB 4 through WEB 10) for the bigger picture. ## Previous Versions npm does not let you rename an existing package in place, so this package has been renamed twice as the OASIS ecosystem evolved, and each rename forced a new package to be created on npm: 1. `oasis-api` (original name) 2. `web4-oasis-api` (renamed as part of the WEB 4 branding) 3. `@oasisomniverse/web4-api` (current — renamed into the `@oasisomniverse` scope alongside the WEB 5-WEB 10 packages, so the whole OASIS Omniverse API family is grouped under one consistent, professional namespace) Both older packages have been deprecated on npm and point here. We keep them published (rather than unpublishing) to preserve their version history and download stats: - https://www.npmjs.com/package/oasis-api - https://www.npmjs.com/package/web4-oasis-api This package starts at `v2.0.0` rather than `v1.0.0` because it is a continuation of that existing `web4-oasis-api` lineage, not a new package — the version numbering picks up where the previous name left off. The other `@oasisomniverse/web5-api` through `@oasisomniverse/web10-api` packages are brand new (no prior published history under any name), so they correctly start at `v1.0.0`. The current version of this package can be found here: https://www.npmjs.com/package/@oasisomniverse/web4-api ## About The OASIS Omniverse The OASIS (Open Advanced Sensory Immersion System) is the universal interoperability layer connecting all of WEB2 and WEB3 — every blockchain, database, cloud provider and protocol — into one unified, fault-tolerant API. Rather than picking a single tech stack, the OASIS harnesses the best of every provider (auto-failover, auto-load-balancing, auto-replication) so nothing is ever a single point of failure, and hides the complexity behind one intuitive API so you never need to learn a new stack again — even as underlying tech evolves (Ethereum 2, Holochain RSM, etc.), your app keeps working with zero changes. At its core sits one Avatar with one SSO login and one Karma reputation score that travels with you across every app, game and world built on top of it — full transparency and full control over your own data, right down to the field level. This is the foundation of the OASIS Omniverse: a network of unified layers, WEB 4 (identity & unification) through WEB 10 (source), each building on the one below to connect blockchains, metaverses, AI, human consciousness and beyond into a single interoperable whole. 👉 See the full ecosystem at **[oasisomniverse.one](https://oasisomniverse.one)**. ## Benefits Of Building On The WEB 4 OASIS API - **Integrate any WEB2 or WEB3 tech into your (web)app without having to learn or worry about new tech stacks/languages.** - **The OASIS handles all cross-chain/cross-provider integration for you.** - **Future prove — new tech (Ethereum2 etc.) gets added for FREE, so you get free upgrades for life.** - **SSO Avatar with a Karma reputation system (full accountability, zero crime, dark-net proof).** - **Maximum integration & interoperability, auto load-balancing, auto fail-over, auto replication.** - **HOT-swappable plugin architecture. HTTP REST/gRPC/GraphQL/CLI/Native endpoints.** - **Javascript, Unity & C# packages — more coming.** - **Write once, deploy everywhere, now and forever — the GOD Protocol/API.** - **Full smart contract interoperability. AI/machine learning over all of the world's aggregated data.** - **Triple-level quantum-resistant encryption & intelligent key management (never lose your keys again).** - **Full redundancy/zero downtime — impossible to shut down. Zero lag. Infinite players online at once.** - **Decentralised distributed P2P networking — works offline and syncs automatically (even over LAN/Bluetooth/Mesh).** - **Agent-centric: you own and store your own data.** - **Powers WEB/2D/3D/AR/VR/IR/Map/Meta visualization, Our World & One World (Game of Games Engine).** - **Smart City ready. Bio-feedback ready. IR (Infinite Reality) ready. WEB 5 Omniverse/Metaverse ready.** Check out more info below:

[The Power Of The OASIS API](https://drive.google.com/file/d/1nnhGpXcprr6kota1Y85HDDKsBfJHN6sn/view?usp=sharing)
[What Is WEB 4 & WEB 5 Really?](https://www.ourworldthegame.com/single-post/what-is-web4-web5-really)
[First Production Release Of The WEB 4 OASIS API](https://www.ourworldthegame.com/single-post/first-production-ready-release-of-web4-oasis-api-more)
[Annoucing WEB 5 STAR ODK/HDK/COSMIC](https://www.ourworldthegame.com/single-post/announcing-star-odk-hdk-cosmic)
[STAR ODK/HDK/COSMIC/OASIS API/Our World Update](https://www.ourworldthegame.com/single-post/star-odk-hdk-cosmic-oasis-api-our-world-update)
[Main WEB 4 OASIS API & WEB 5 STAR Repo](https://github.com/NextGenSoftwareUK/OASIS) ## WEB 4 OASIS API Packages ### Javascript \ ### Unity ### C# ## Do You Want To Get Involved? We are always looking for people to jump in and get involved, you do not need to be an existing coder, we can help you with that... you just need a willingness to learn and to have an open heart, we are always more interested with what is in your heart rather than your head! ;-) The whole world is the Our World team, hence the name... ;-) It is not our project; it is all of humanities... We also offer FREE training and apprenticeship program with the NextGen Developer Training Programmes. We will teach you all we know over time and you get to work on this real live commercial codebase rather than wasting time working on throw away dummy apps as most training offers. No previous skills/experience required and is open to everyone, but especially for all disadvantaged people including special needs, homeless, unemployed, prison inmates, kids on the streets etc. We want to help the people the world has forgotten and for people who have stopped believing in themselves, we **BELIEVE IN YOU** and in time you will again too. Everyone has a gift for the world, and we will help you find yours… Find out more by checking out the links below: NextGen Developer Training Programme
NextGen Junior Developer Training Programme We are looking for Web Devs (with any of these: react, angular, vue, js, html, css), Unity Devs & C# Devs. If anyone is interested in developing this game/platform, then we would LOVE to hear from you! 😊 There will be opportunities for people to earn tokens/NFTs (as well as other unique perks such as premium locations in both the geolocation and VR versions, personal or business service spotlights, free lifetime access to all premium paid services, massive karma points (allowing your avatar to progress to more advanced stages in the game unlocking new exciting quests, areas to explore & new special abilities/superpowers) plus lots more!) based on the input they are willing to provide. Thank you and we hope we find interest from people to join us on this exciting incredible journey. **Want to make a difference in the world?** **What will be your legacy?** **Ready to be a hero?** If the answer is YES, then please [proceed to here](https://github.com/NextGenSoftwareUK/OASIS/wiki/So-You-Want-To-Get-Involved%3F-Ready-To-Be-A-Hero%3F)... Dev Requirements To Join The Our World Tribe
The Our World Mission (Summary)













**TOGETHER WE CAN CREATE A BETTER WORLD** In Love, Light & Hope,
The Our World Tribe ## Install ```bash npm install @oasisomniverse/web4-api ``` ## Quick start ```js const { OASISClient } = require('@oasisomniverse/web4-api'); // or: import { OASISClient } from '@oasisomniverse/web4-api'; const oasis = new OASISClient({ baseUrl: 'https://api.oasisweb4.one' }); const { isError, message, session } = await oasis.auth.login({ username: 'me@example.com', // username or email both work password: 'correct-horse-battery-staple' }); if (isError) throw new Error(message); const { result: karma } = await oasis.karma.getKarmaForAvatar({ avatarId: session.avatarId }); ``` ## Calling any endpoint Every controller on the OASIS ONODE WebAPI is reachable as a lowerCamel property on the client (`oasis.avatar`, `oasis.karma`, `oasis.data`, `oasis.wallet`, `oasis.nft`, `oasis.holochain`, ...). Every generated method takes a single args object: - Any key matching a `{token}` in the route template is consumed and substituted into the URL (case-insensitive match). - Any remaining keys become the query string (GET/DELETE) or JSON body (POST/PUT) - **matching the real `[FromQuery]`/`[FromBody]` binding of the underlying C# action**, not just the HTTP verb. `endpoints.json` records exactly which arg names are query-bound per operation (see [`docs/`](./docs/README.md) for the per-method breakdown). - When an action's entire body is a single primitive `[FromBody]` parameter, the JSON body is that value directly - not an object wrapping it. Every response has the shape: ```ts interface OASISResponse { isError: boolean; message: string | null; result: T; raw: any; statusCode: number; } ``` ## Auth & sessions `oasis.auth` is a hand-written ergonomic wrapper that manages the SDK's `TokenStore` for you so you don't have to think about JWTs. ```js const loginRes = await oasis.auth.login({ username: 'me@example.com', password: '...' }); if (loginRes.isError) throw new Error(loginRes.message); console.log(oasis.auth.isAuthenticated()); // true console.log(oasis.auth.getSession()); // { avatarId, username, email, jwtToken, ... } await oasis.auth.logout(); // clears the local session ``` If you already have a JWT (e.g. issued by your own backend), set it directly: ```js oasis.setToken(jwtToken, { avatarId, username }); ``` ## Module examples ### Avatar (`oasis.avatar`) ```js const detail = await oasis.avatar.getAvatarDetail({ id: avatarId }); await oasis.avatar.update({ id: avatarId, username: 'newname' }); await oasis.avatar.addKarmaToAvatar({ avatarId, karmaGain: 5, karmaSourceTitle: 'Recycling' }); ``` ### Karma (`oasis.karma`) ```js const karma = await oasis.karma.getKarmaForAvatar({ avatarId }); await oasis.karma.removeKarmaFromAvatar({ avatarId, karmaLoss: 10, karmaSourceTitle: 'Litter' }); ``` ### Data (`oasis.data`) ```js const holon = await oasis.data.loadHolon({ holonId }); await oasis.data.saveHolon({ /* ...holon fields */ }); ``` ### Wallet (`oasis.wallet`) ```js const wallets = await oasis.wallet.loadProviderWalletsForAvatarByIdAsync({ id: avatarId }); await oasis.wallet.sendTokenAsync({ /* ...SendTransactionRequest fields */ }); await oasis.wallet.transferBetweenWalletsAsync({ /* ...TransferRequest fields */ }); ``` ### NFT (`oasis.nft`) ```js const nfts = await oasis.nft.loadAllWeb4NFTsForAvatarAsync({ avatarId }); await oasis.nft.mintNftAsync({ /* ...MintNFTRequest fields */ }); ``` ### Holochain (`oasis.holochain`) ```js const agentIds = await oasis.holochain.getHolochainAgentIdsForAvatar({ avatarId }); const balance = await oasis.holochain.getHoloFuelBalanceForAvatar({ avatarId }); ``` ## Module reference 32 modules, 483 operations in total. Full per-method tables live in [`docs/`](./docs/README.md). | Client property | Route prefix | Operations | | --- | --- | --- | | `oasis.avatar` | `api/avatar` | 61 | | `oasis.bridge` | `api/v1/bridge` | 7 | | `oasis.chat` | `api/chat` | 3 | | `oasis.clan` | `api/clan` | 10 | | `oasis.competition` | `api/competition` | 9 | | `oasis.data` | `api/data` | 10 | | `oasis.eOSIO` | `api/eosio` | 9 | | `oasis.eggs` | `api/eggs` | 6 | | `oasis.files` | `api/files` | 6 | | `oasis.gifts` | `api/gifts` | 6 | | `oasis.health` | `api/health` | 2 | | `oasis.holochain` | `api/holochain` | 7 | | `oasis.hyperDrive` | `api/hyperDrive` | 77 | | `oasis.karma` | `api/karma` | 12 | | `oasis.keys` | `api/keys` | 59 | | `oasis.map` | `api/map` | 22 | | `oasis.messaging` | `api/messaging` | 6 | | `oasis.nft` | `api/nft` | 32 | | `oasis.oLand` | `api/oLand` | 7 | | `oasis.oNET` | `api/v1/onet` | 11 | | `oasis.oNODE` | `api/v1/onode` | 13 | | `oasis.provider` | `api/provider` | 31 | | `oasis.search` | `api/search` | 1 | | `oasis.seeds` | `api/seeds` | 3 | | `oasis.settings` | `api/settings` | 13 | | `oasis.share` | `api/share` | 1 | | `oasis.social` | `api/social` | 4 | | `oasis.solana` | `api/solana` | 2 | | `oasis.stats` | `api/stats` | 8 | | `oasis.subscription` | `api/subscription` | 10 | | `oasis.video` | `api/video` | 3 | | `oasis.wallet` | `api/wallet` | 32 | See [`docs/README.md`](./docs/README.md) for the full generated reference, or [`docs/modules/`](./docs/modules) for per-module method tables with parameter and route details. ## Regenerating The generated modules, type declarations and docs are produced from `endpoints.json` (extracted from the ONODE WebAPI controller source): ```bash node scripts/extract-endpoints.js node scripts/generate-modules.js # src/modules/*.js + src/modules/index.js node scripts/generate-types.js # src/modules/*.d.ts + index.d.ts + src/core/types.d.ts node scripts/generate-full-docs.js # docs/README.md + docs/modules/*.md ``` `src/modules/Auth.js` is the one hand-written module (everything else is generated) - see [docs/auth.md](./docs/auth.md) for details. ## Testing ```bash npm test ``` ## Full documentation - **[docs/getting-started.md](./docs/getting-started.md)** - install, client options, the calling convention, response shape. - **[docs/auth.md](./docs/auth.md)** - login/register/logout, session handling in the browser vs. serverless/Node. - **[docs/README.md](./docs/README.md)** - full module reference: every one of the 32 modules / 483 operations, with HTTP verb, route, route params, and an example call for each. - **[docs/troubleshooting.md](./docs/troubleshooting.md)** - common errors and fixes. Docs are generated from the actual code (`scripts/generate-docs.js` parses `src/modules/*.js`), so they can't drift from what's actually implemented. ## Troubleshooting See **[docs/troubleshooting.md](./docs/troubleshooting.md)** for the full list. Most common issue: **`Failed to execute 'fetch' on 'Window': Illegal invocation`** when bundling with esbuild, Webpack, Rollup, or Vite — add this one line before your SDK script loads: ```html ``` Or pass a pre-bound `fetchImpl` when constructing the client: ```js const client = new OASISClient({ baseUrl: 'https://api.web4.oasisomniverse.one', fetchImpl: window.fetch.bind(window) }); ```