Portals Protocol

https://portalsprotocol.com/docs
Admin
Portals Protocol is an on-chain app store for AI agents that connects agents to third-party APIs...
Tokens:4,992
Snippets:67
Trust Score:4.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://portalsprotocol.com/docs/client-sdk

Install the Portals Client SDK and the Solana Web3.js library using npm.

```APIDOC
## Installation

```
npm install @portalsprotocol/client @solana/web3.js
```
```

--------------------------------

### Install Portals Client SDK

Source: https://portalsprotocol.com/docs/client-sdk

Install the necessary packages for the Portals Client SDK and Solana web3.js.

```bash
npm install @portalsprotocol/client @solana/web3.js

```

--------------------------------

### Install Dependencies

Source: https://portalsprotocol.com/docs/quick-start

Install the necessary Hono and x402-hono packages for your project. If using Cloudflare Workers, also install Wrangler.

```bash
npm install hono x402-hono


```

--------------------------------

### MCP Server Environment Variables Example

Source: https://portalsprotocol.com/docs/mcp-server

Example of MCP server environment variables, including custom network and RPC endpoint. Ensure PORTALS_WHITELIST is set to your desired portal IDs.

```json
"env": {
  "PORTALS_WHITELIST": "ABC123,XYZ789",
  "PORTALS_NETWORK": "devnet",
  "PORTALS_RPC": "https://api.devnet.solana.com"
}

```

--------------------------------

### Example Agent Prompt for Tool Usage

Source: https://portalsprotocol.com/docs/user-quickstart

Once configured and funded, your agent can use whitelisted Portals by including them in prompts. The MCP server handles the backend operations.

```text
"Search Twitter for mentions of Solana"

```

--------------------------------

### Get Wallet Balance

Source: https://portalsprotocol.com/docs/client-sdk

Retrieve the SOL and USDC balances for the current wallet.

```APIDOC
## Fund the Wallet

Before calling any Portal, fund the wallet with:
  * **SOL** for gas fees.
  * **USDC** for API payments.

```typescript
const balance = await client.getBalance();
console.log('SOL:', balance.sol, 'USDC:', balance.usdc);
```
```

--------------------------------

### Error Handling

Source: https://portalsprotocol.com/docs/client-sdk

Example of how to handle specific typed errors thrown by the SDK during API calls.

```APIDOC
## Error Handling

The SDK throws typed errors you can handle explicitly.
```typescript
import {
  PricingMismatch,
  PaymentAddressMismatch,
  InsufficientSolBalance,
  InsufficientUsdcBalance,
} from '@portalsprotocol/client';

try {
  const result = await client.callAPI(...);
  console.log(result);
} catch (error) {
  if (error instanceof PricingMismatch) {
    console.error('Provider price does not match schema:', error.message);
  } else if (error instanceof PaymentAddressMismatch) {
    console.error('Payment address did not match the on-chain vault:', error.message);
  } else if (error instanceof InsufficientSolBalance || error instanceof InsufficientUsdcBalance) {
    console.error('Top up the wallet before retrying:', error.message);
  } else {
    console.error('Unexpected Portals error:', (error as Error).message);
  }
}
```
```

--------------------------------

### Get Wallet Balance

Source: https://portalsprotocol.com/docs/client-sdk

Retrieve the current SOL and USDC balances for the wallet managed by the PortalsClient.

```typescript
const balance = await client.getBalance();
console.log('SOL:', balance.sol, 'USDC:', balance.usdc);

```

--------------------------------

### Create or Load Wallet with PortalsClient

Source: https://portalsprotocol.com/docs/client-sdk

Initialize the PortalsClient by either creating a new wallet or loading an existing one from a file. Specify the network for the client.

```typescript
import { PortalsClient } from '@portalsprotocol/client';

// Option A: create a new wallet (dev/testing)
const client = PortalsClient.createNew({
  walletPath: './portals-wallet.json',
  network: 'mainnet-beta', // or 'devnet'
});

// Option B: load an existing wallet
// const client = PortalsClient.fromFile({
//   walletPath: './portals-wallet.json',
//   network: 'mainnet-beta',
// });

console.log('Wallet:', client.getAddress().toBase58());

```

--------------------------------

### Create or Load a Wallet

Source: https://portalsprotocol.com/docs/client-sdk

Initialize the PortalsClient by either creating a new wallet or loading an existing one from a file.

```APIDOC
## Create or Load a Wallet

```typescript
import { PortalsClient } from '@portalsprotocol/client';

// Option A: create a new wallet (dev/testing)
const client = PortalsClient.createNew({
  walletPath: './portals-wallet.json',
  network: 'mainnet-beta', // or 'devnet'
});

// Option B: load an existing wallet
// const client = PortalsClient.fromFile({
//   walletPath: './portals-wallet.json',
//   network: 'mainnet-beta',
// });

console.log('Wallet:', client.getAddress().toBase58());
```
```

--------------------------------

### Serve OpenAPI Schema with Pricing

Source: https://portalsprotocol.com/docs/quick-start

Expose an OpenAPI JSON document at '/openapi.json' that describes your API endpoints and their associated pricing using the 'x-portals-pricing' extension. This allows agents to discover and price your tools.

```typescript
app.get('/openapi.json', (c) => {
  return c.json({
    openapi: '3.1.0',
    info: {
      title: 'My Portal',
      description: 'Example Portal with a paid search endpoint',
      version: '1.0.0',
    },
    paths: {
      '/search': {
        post: {
          operationId: 'search_data',
          summary: 'Search data',
          'x-portals-pricing': {
            type: 'fixed',
            price: 0.01,
          },
          requestBody: {
            required: true,
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    query: { type: 'string', description: 'Search query' },
                  },
                  required: ['query'],
                },
              },
            },
          },
          responses: {
            '200': { description: 'Success' },
            '402': { description: 'Payment required' },
          },
        },
      },
    },
  });
});

```

--------------------------------

### MCP Server Configuration for Portals

Source: https://portalsprotocol.com/docs/user-quickstart

Paste this JSON snippet into your agent's MCP settings file to enable Portals. Ensure the PORTALS_WHITELIST includes the IDs of the Portals you want to enable.

```json
{
  "mcpServers": {
    "portals": {
      "command": "npx",
      "args": ["-y", "@portalsprotocol/mcp-server"],
      "env": {
        "PORTALS_WHITELIST": "portal_id_1,portal_id_2,portal_id_3"
      }
    }
  }
}

```

--------------------------------

### Find a Portal and Call a Tool

Source: https://portalsprotocol.com/docs/client-sdk

Discover Portals by searching for a keyword, then call a specific tool (operationId) on the selected Portal, handling the 402 payment flow.

```APIDOC
## Find a Portal and Call a Tool

```typescript
// 1. Discover Portals from the on-chain registry
const apis = await client.searchAPIs('twitter');
if (!apis.length) throw new Error('No Portals found');

const portal = apis[0];

// 2. Call a specific tool (operationId from the Portal's OpenAPI schema)
const result = await client.callAPI(
  portal.publicKey.toString(),
  { query: 'latest solana news' },
  'search_tweets', // operationId
);

console.log('Result:', result);
```
```

--------------------------------

### Core Methods

Source: https://portalsprotocol.com/docs/client-sdk

Reference for the core methods available in the Portals Client SDK.

```APIDOC
## Core Methods

  * **`PortalsClient.createNew(options)`**: creates a new wallet on disk and returns a client instance.
  * **`PortalsClient.fromFile(options)`**: loads an existing wallet from`walletPath`.
  * **`client.getAddress()`**: returns the wallet`PublicKey`.
  * **`client.getBalance()`**: returns`{ sol, usdc }` for the current wallet.
  * **`client.searchAPIs(keyword?)`**: queries the registry for Portals matching an optional keyword.
  * **`client.callAPI(portalId, params, toolName?)`**: calls a Portal tool and handles the full 402 payment loop.

`toolName` is the **`operationId`**from the Portal's OpenAPI schema (`/openapi.json`). If omitted, the client will just call the base URL.
```

--------------------------------

### Configure MCP Server in Agent Config

Source: https://portalsprotocol.com/docs/mcp-server

Add this configuration to your agent's MCP config file to enable the Portals server. Specify whitelisted portals using the PORTALS_WHITELIST environment variable.

```json
{
  "mcpServers": {
    "portals": {
      "command": "npx",
      "args": ["-y", "@portalsprotocol/mcp-server"],
      "env": {
        "PORTALS_WHITELIST": "portal_id_1,portal_id_2"
      }
    }
  }
}

```

--------------------------------

### Search Portals and Call API

Source: https://portalsprotocol.com/docs/client-sdk

Discover available Portals by searching for a keyword and then call a specific tool (operationId) on the selected Portal. This handles the 402 payment flow.

```typescript
// 1. Discover Portals from the on-chain registry
const apis = await client.searchAPIs('twitter');
if (!apis.length) throw new Error('No Portals found');

const portal = apis[0];

// 2. Call a specific tool (operationId from the Portal's OpenAPI schema)
const result = await client.callAPI(
  portal.publicKey.toString(),
  { query: 'latest solana news' },
  'search_tweets', // operationId
);

console.log('Result:', result);

```

--------------------------------

### Handle Portals SDK Errors

Source: https://portalsprotocol.com/docs/client-sdk

Implement error handling for specific Portals SDK exceptions such as pricing mismatches, payment address issues, or insufficient balances.

```typescript
import {
  PricingMismatch,
  PaymentAddressMismatch,
  InsufficientSolBalance,
  InsufficientUsdcBalance,
} from '@portalsprotocol/client';

try {
  const result = await client.callAPI(...);
  console.log(result);
} catch (error) {
  if (error instanceof PricingMismatch) {
    console.error('Provider price does not match schema:', error.message);
  } else if (error instanceof PaymentAddressMismatch) {
    console.error('Payment address did not match the on-chain vault:', error.message);
  } else if (error instanceof InsufficientSolBalance || error instanceof InsufficientUsdcBalance) {
    console.error('Top up the wallet before retrying:', error.message);
  } else {
    console.error('Unexpected Portals error:', (error as Error).message);
  }
}

```

--------------------------------

### Add x402 Payment Middleware to Hono App

Source: https://portalsprotocol.com/docs/quick-start

Apply the paymentMiddleware to specific routes in your Hono application to enforce payment for API calls. Ensure environment variables like FACILITATOR_URL, NETWORK, and PAYMENT_ADDRESS_PORTAL are correctly configured.

```typescript
import { Hono } from 'hono';
import { paymentMiddleware } from 'x402-hono';

type Bindings = {
  FACILITATOR_URL: string;
  NETWORK: string;
  PAYMENT_ADDRESS_PORTAL: string;
};

const app = new Hono<{ Bindings: Bindings }>();

app.use('/portal/*', async (c, next) => {
  const path = new URL(c.req.url).pathname.replace('/portal', '');
  const price = '$0.01';
  const network = c.env.NETWORK as any;

  const middleware = paymentMiddleware(
    c.env.PAYMENT_ADDRESS_PORTAL as `0x${string}`,
    { [path]: { price, network } },
    { url: c.env.FACILITATOR_URL as `${string}://${string}` }
  );

  return middleware(c, next);
});

app.post('/portal/search', async (c) => {
  const body = await c.req.json<{ query: string }>();
  return c.json({ ok: true, query: body.query });
});

export default app;

```
Tokens:
Raw