# retrieval

OpenAPI spec: [https://api.payweave.app/app/app_egn8dkffz76sfac0dhxxioty/openapi.json](https://api.payweave.app/app/app_egn8dkffz76sfac0dhxxioty/openapi.json)

## Networks

| Name | Mode | CAIP-2 | Chain ID / Cluster |
|---|---|---|---|
| Tempo Mainnet | live | `eip155:4217` | 4217 |
| Solana Mainnet | live | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | mainnet-beta |

## Accepted Currencies

| Symbol | Name | Decimals | Network | Address |
|---|---|---|---|---|
| USDC.e | Bridged USDC (Stargate) | 6 | `eip155:4217` | `0x20c000000000000000000000b9537d11c60e8b50` |
| USDC | USD Coin (Solana) | 6 | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |

## Endpoints (2)

### Retrieval: Text Embeddings

Embed 1-100 texts into vectors using Cloudflare Workers AI BGE models (`bge-base` 768d default, `bge-large` 1024d, or multilingual `bge-m3` 1024d). Returns one vector per input text. Priced per text.

- Method: POST
- Path: `/embed`
- Price: $0.00020000

**Input Schema**

```json
{
  "type": "object",
  "properties": {
    "texts": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2000
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Texts to embed, in order. 1-100 items, each up to 2000 characters. Priced per text."
    },
    "model": {
      "type": "string",
      "enum": [
        "bge-base",
        "bge-large",
        "bge-m3"
      ],
      "description": "Embedding model: `bge-base` (768d, default), `bge-large` (1024d, higher quality), or `bge-m3` (1024d, multilingual). Defaults to `bge-base`."
    }
  },
  "required": [
    "texts"
  ],
  "additionalProperties": false
}
```

**Output Schema**

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Workers AI model id used"
    },
    "dimensions": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Length of each embedding vector"
    },
    "embeddings": {
      "type": "array",
      "items": {
        "type": "array",
        "items": {
          "type": "number"
        }
      },
      "description": "One embedding vector per input text, in the same order as `texts`"
    }
  },
  "required": [
    "model",
    "dimensions",
    "embeddings"
  ],
  "additionalProperties": false,
  "description": "Embedding vectors for the input texts"
}
```

## How to invoke

Payment is handled automatically — the client signs the 402 challenge and retries.

### TypeScript — Tempo (mppx + fetch) ([docs](https://mpp.dev/sdk/typescript/client))

```ts
import { privateKeyToAccount } from 'viem/accounts'
import { Mppx, tempo } from 'mppx/client'

Mppx.create({
  methods: [tempo({ account: privateKeyToAccount('0x...') })],
})

const res = await fetch('https://retrieval.payweave.services/embed', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "texts": [
      ""
    ],
    "model": "bge-base"
  }),
})
const data = await res.json()
```

### TypeScript — Solana (@solana/mpp + fetch) ([docs](https://github.com/solana-foundation/mpp-sdk))

```ts
import { createKeyPairSignerFromBytes } from '@solana/kit'
import { Mppx } from 'mppx/client'
import { solana } from '@solana/mpp/client'

const signer = await createKeyPairSignerFromBytes(/* 64-byte secret key */)
Mppx.create({ methods: [solana({ signer })] })

const res = await fetch('https://retrieval.payweave.services/embed', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "texts": [
      ""
    ],
    "model": "bge-base"
  }),
})
const data = await res.json()
```

### mppx CLI ([docs](https://mpp.dev/sdk/typescript/cli))

```sh
npx mppx "https://retrieval.payweave.services/embed" -X POST -H 'Content-Type: application/json' -d '{"texts":[""],"model":"bge-base"}'
```

### Tempo Wallet ([docs](https://docs.tempo.xyz/cli/wallet))

```sh
tempo request "https://retrieval.payweave.services/embed" -X POST --json '{"texts":[""],"model":"bge-base"}'
```

### pay.sh — Solana Foundation ([docs](https://pay.sh))

```sh
pay --mainnet curl "https://retrieval.payweave.services/embed" -X POST -H 'Content-Type: application/json' -d '{"texts":[""],"model":"bge-base"}'
```

### Retrieval: Rerank

Reorder up to 50 candidate documents by relevance to a query using Cloudflare Workers AI `@cf/baai/bge-reranker-base`. Returns documents with relevance scores, highest first. Pair with /embed to build a retrieve-then-rerank RAG pipeline.

- Method: POST
- Path: `/rerank`
- Price: $0.00100000

**Input Schema**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The search query. Up to 2000 characters."
    },
    "documents": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2000
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "Candidate documents to score against the query. 1-50 items, each up to 2000 characters."
    },
    "top_k": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Return only the top K highest-scoring documents. Defaults to all, ranked."
    }
  },
  "required": [
    "query",
    "documents"
  ],
  "additionalProperties": false
}
```

**Output Schema**

```json
{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "description": "Index into the input `documents` array"
          },
          "score": {
            "type": "number",
            "description": "Relevance score; higher is more relevant"
          },
          "document": {
            "type": "string",
            "description": "The document text at `index`"
          }
        },
        "required": [
          "index",
          "score",
          "document"
        ],
        "additionalProperties": false
      },
      "description": "Documents ordered by descending relevance score"
    }
  },
  "required": [
    "results"
  ],
  "additionalProperties": false,
  "description": "Reranked documents"
}
```

## How to invoke

Payment is handled automatically — the client signs the 402 challenge and retries.

### TypeScript — Tempo (mppx + fetch) ([docs](https://mpp.dev/sdk/typescript/client))

```ts
import { privateKeyToAccount } from 'viem/accounts'
import { Mppx, tempo } from 'mppx/client'

Mppx.create({
  methods: [tempo({ account: privateKeyToAccount('0x...') })],
})

const res = await fetch('https://retrieval.payweave.services/rerank', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "query": "",
    "documents": [
      ""
    ],
    "top_k": 1
  }),
})
const data = await res.json()
```

### TypeScript — Solana (@solana/mpp + fetch) ([docs](https://github.com/solana-foundation/mpp-sdk))

```ts
import { createKeyPairSignerFromBytes } from '@solana/kit'
import { Mppx } from 'mppx/client'
import { solana } from '@solana/mpp/client'

const signer = await createKeyPairSignerFromBytes(/* 64-byte secret key */)
Mppx.create({ methods: [solana({ signer })] })

const res = await fetch('https://retrieval.payweave.services/rerank', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "query": "",
    "documents": [
      ""
    ],
    "top_k": 1
  }),
})
const data = await res.json()
```

### mppx CLI ([docs](https://mpp.dev/sdk/typescript/cli))

```sh
npx mppx "https://retrieval.payweave.services/rerank" -X POST -H 'Content-Type: application/json' -d '{"query":"","documents":[""],"top_k":1}'
```

### Tempo Wallet ([docs](https://docs.tempo.xyz/cli/wallet))

```sh
tempo request "https://retrieval.payweave.services/rerank" -X POST --json '{"query":"","documents":[""],"top_k":1}'
```

### pay.sh — Solana Foundation ([docs](https://pay.sh))

```sh
pay --mainnet curl "https://retrieval.payweave.services/rerank" -X POST -H 'Content-Type: application/json' -d '{"query":"","documents":[""],"top_k":1}'
```