# Relay

OpenAPI spec: [https://api.payweave.app/app/app_z4jqboizri5s1y5cyyp2mnkj/openapi.json](https://api.payweave.app/app/app_z4jqboizri5s1y5cyyp2mnkj/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 (3)

### Relay: Create Webhook Inbox

Create a durable webhook inbox and get a public callback URL. External systems (or a human clicking a link) POST to that URL; capture the events later via GET /inboxes/{id}/events. Priced by TTL tier (1d/7d/30d).

- Method: POST
- Path: `/inboxes`
- Price: $0.00300000

**Input Schema**

```json
{
  "type": "object",
  "properties": {
    "ttlDays": {
      "type": "integer",
      "minimum": 1,
      "maximum": 30,
      "description": "Inbox lifetime in days (1-30, default 1). Priced in tiers: <=1d, <=7d, <=30d."
    }
  },
  "additionalProperties": false
}
```

**Output Schema**

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "callbackUrl": {
      "type": "string"
    },
    "expiresAt": {
      "type": "number"
    },
    "capacity": {
      "type": "number"
    },
    "ttlDays": {
      "type": "number"
    }
  },
  "required": [
    "id",
    "callbackUrl",
    "expiresAt",
    "capacity",
    "ttlDays"
  ],
  "additionalProperties": false
}
```

## 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://relay.payweave.services/inboxes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "ttlDays": 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://relay.payweave.services/inboxes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "ttlDays": 1
  }),
})
const data = await res.json()
```

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

```sh
npx mppx "https://relay.payweave.services/inboxes" -X POST -H 'Content-Type: application/json' -d '{"ttlDays":1}'
```

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

```sh
tempo request "https://relay.payweave.services/inboxes" -X POST --json '{"ttlDays":1}'
```

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

```sh
pay --mainnet curl "https://relay.payweave.services/inboxes" -X POST -H 'Content-Type: application/json' -d '{"ttlDays":1}'
```

### Relay: Delete Inbox

Delete an inbox and all its captured events. Owner-scoped.

- Method: DELETE
- Path: `/inboxes/:id`
- Price: $0.00050000

## 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://relay.payweave.services/inboxes/:id', {
  method: 'DELETE',
})
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://relay.payweave.services/inboxes/:id', {
  method: 'DELETE',
})
const data = await res.json()
```

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

```sh
npx mppx "https://relay.payweave.services/inboxes/:id" -X DELETE
```

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

```sh
tempo request "https://relay.payweave.services/inboxes/:id" -X DELETE
```

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

```sh
pay --mainnet curl "https://relay.payweave.services/inboxes/:id" -X DELETE
```

### Relay: Read Inbox Events

Read events captured by an inbox. Query params: `since` (cursor from a previous response, returns only newer events) and `wait` (seconds to long-poll for the next event, max 30; returns as soon as one arrives). Owner-scoped: only the wallet that created the inbox can read it. Flat price regardless of wait duration.

- Method: GET
- Path: `/inboxes/:id/events`
- Price: $0.00100000

**Output Schema**

```json
{
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "seq": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "receivedAt": {
            "type": "number"
          },
          "method": {
            "type": "string"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "query": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "body": {
            "type": [
              "string",
              "null"
            ]
          },
          "bodyTruncated": {
            "type": "boolean"
          },
          "contentType": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "seq",
          "id",
          "receivedAt",
          "method",
          "headers",
          "query",
          "body",
          "bodyTruncated",
          "contentType"
        ],
        "additionalProperties": false
      }
    },
    "cursor": {
      "type": "number"
    },
    "dropped": {
      "type": "number"
    }
  },
  "required": [
    "events",
    "cursor",
    "dropped"
  ],
  "additionalProperties": false
}
```

## 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://relay.payweave.services/inboxes/:id/events')
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://relay.payweave.services/inboxes/:id/events')
const data = await res.json()
```

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

```sh
npx mppx "https://relay.payweave.services/inboxes/:id/events"
```

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

```sh
tempo request "https://relay.payweave.services/inboxes/:id/events"
```

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

```sh
pay --mainnet curl "https://relay.payweave.services/inboxes/:id/events"
```