Subscriptions

Create a subscription

Reserves a subscription to one of your plans for the wallet named, and builds what that wallet signs: the terms, as a message, then the transaction, without sending it. Hand both to Submit.

The transaction lives 150 blocks, about half a minute: transaction_expires_at estimates when they run out, last_valid_block_height says it. The terms live five minutes. Have the terms signed first, then ask for a fresh transaction when the wallet is ready to sign it.

Called again for the same plan, wallet and customer while nothing has landed, it answers the same subscription with a fresh transaction. The customer is the external_id, else the email, else nobody. Another customer naming the same wallet gets a subscription of its own: only the one the wallet signs for lands.

A wallet whose subscription to this plan stopped comes back over its existing authorisation: a new subscription, with costs.rent at zero.

On a plan with an end date, terms.message says that the last charge is in full and that access stops when the plan ends. When the plan ends before a second charge can be made, it says the charge is a single one.

POSThttps://api.mesub.io/v1/subscriptions

POSTCreate a subscription

https://api.mesub.io/v1/subscriptions

Calls are real. They go to https://api.mesub.io and act on the project the key belongs to.

Authorization

API keyBearerrequired

The key stays in this browser and is sent only to the API. It is not stored or logged by the docs.

Keep it until this tab closes

Body

planstringrequired

walletstringrequired

external_idstring

emailstring<email>

Fill plan, wallet to send.

cURL

curl -X POST "https://api.mesub.io/v1/subscriptions" \
  -H "Authorization: Bearer $MESUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

Send the request to see the status, the headers and the body.

Limit: 60 calls a minute per API key.Guide: Subscribe from your server.

Headers

Mesub-Versionenum<string>

The version of this contract the call is written against. Without it, the call is served as the first version, 2026-10-02. Any other value is refused with 400 unsupported_version.

One of2026-10-02

Body

application/json

planstringrequired

The plan's slug: lowercase letters, digits and single hyphens.

walletstringrequired

The wallet that signs the terms and the transaction, and pays. A base58 Solana address.

external_idstring

Your own id for this customer, handed back as given. It is how GET /v1/access finds them later, whichever wallet pays.

emailstring<email>

Where the customer's notices go. Not verified by Mesub. Trimmed and lowercased.

Response

application/json

The subscription, pending, and what the wallet signs.

Headers

Mesub-Versionenum<string>

The version the answer is written in: the one asked for, or 2026-10-02 when the call named none, or one this API does not serve.

One of2026-10-02

Mesub-Request-Idstring

The id Mesub gave this request, on every answer, errors included, and in request_id on an error body. Quote it to Mesub support to find the request in our logs. Written by Mesub on each request: one sent with the request is ignored.

X-RateLimit-Limitintegernot always present

The calls this route allows the API key in a minute, or the IP of a call without a valid key. Sent on every answer the rate limit counted.

X-RateLimit-Remainingintegernot always present

What is left of them in the current minute.

X-RateLimit-Resetintegernot always present

Seconds until the count starts again.

subscriptionobject

Show child attributesHide child attributes

idstring

Keep it: every later call names it.

statusenum<string>

One ofpending

transactionstring

Base64, signed by nobody. The wallet signs it without sending it.

last_valid_block_heightstring

The block height after which the transaction can no longer land.

transaction_expires_atstring<date-time>

When last_valid_block_height is expected to pass: an estimate, about half a minute after the answer. Mesub reads it from how fast block heights went (skipped slots included), taking the faster of the last half hour and the last 30 seconds, and counts the blocks the chain's tip is ahead of what it read, so the estimate errs early, not late, while the chain keeps its pace. The height is the truth: rebuild the transaction when the chain refuses it with an expired blockhash, before this time as after it. Use this for a countdown, or to ask for a fresh transaction before it runs out.

costsobject

What subscribing costs the wallet in SOL, in lamports, as strings.

Show child attributesHide child attributes

rentobject

A deposit the customer gets back when the subscription is closed.

Show child attributesHide child attributes

subscriptionstring

authoritystring | null

Null when the customer already has an authority for that token.

totalstring

feeobject

Spent, not returned.

Show child attributesHide child attributes

signaturesinteger

per_signaturestring

prioritystring

totalstring

termsobject

Show child attributesHide child attributes

messagestring

Plain text, one fact per line. The wallet signs it as is, before the transaction.

expires_atstring<date-time>

Five minutes after the terms were handed out. Submit before it.

Authorizations

Authorizationstring · headerrequired

Bearer <API key>. The project's API key, which starts with SUB_. Keep it on your server. Where to get it.

Ask AI about this page

Request example

curl -X POST "https://api.mesub.io/v1/subscriptions" \
  -H "Authorization: Bearer $MESUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "plan": "pro",
  "wallet": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "external_id": "user_42",
  "email": "[email protected]"
}'

Response example

{
    "subscription": {
        "id": "cmg1x0abc0001",
        "status": "pending"
    },
    "transaction": "gAIBBg0Xq3ZkT9yLmR4vP7wJ8sN2aHcVbE5uYtKfDgQxWz1oMiCj6rA0lSnUhBdXe2GqFpYv7mNcTz4RwK8sLjH5AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQIDBAUGBwgJCgsM",
    "last_valid_block_height": "301245678",
    "transaction_expires_at": "2026-01-01T00:00:33.000Z",
    "costs": {
        "rent": {
            "subscription": "1969680",
            "authority": "1628640",
            "total": "3598320"
        },
        "fee": {
            "signatures": 2,
            "per_signature": "5000",
            "priority": "0",
            "total": "10000"
        },
        "total": "3608320"
    },
    "terms": {
        "message": "Mesub: the terms of the subscription...\nAmount: 9.99 USDC every month\n...",
        "expires_at": "2026-01-01T00:05:00.000Z"
    }
}